---
title: Analytics API
description: Document completion rates, signing metrics, and workspace activity trends
---

# Analytics API

The Analytics API provides document-level metrics and workspace-level snapshots for your organization. Use it to track signing performance, measure completion rates, and monitor overall workspace health.

## The Analytics Object

### Attributes

| Attribute            | Type   | Description                                                      |
| -------------------- | ------ | ---------------------------------------------------------------- |
| `period`             | object | The date range this report covers                                |
| `period.from`        | string | ISO 8601 start of the reporting period                           |
| `period.to`          | string | ISO 8601 end of the reporting period                             |
| `documents`          | object | Aggregate document metrics for the period                        |
| `workspace_snapshot` | object | Point-in-time counts by workflow status (all-time, not filtered) |

### Document Metrics

| Field                  | Type           | Description                                                                                             |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `total_created`        | number         | Documents created during the period                                                                     |
| `total_sent`           | number         | Documents sent for signing during the period                                                            |
| `total_completed`      | number         | Documents fully signed during the period                                                                |
| `total_cancelled`      | number         | Documents voided during the period                                                                      |
| `total_declined`       | number         | Documents declined during the period                                                                    |
| `completion_rate`      | number         | Percentage of resolved documents that completed: `completed / (completed + cancelled + declined) × 100` |
| `median_signing_hours` | number \| null | Median hours from sent to completed (null if fewer than 2 completed docs)                               |

### Workspace Snapshot

| Field         | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| `draft`       | number | All-time count of documents currently in draft |
| `sent`        | number | All-time count of documents currently sent     |
| `in_progress` | number | All-time count of documents in progress        |
| `completed`   | number | All-time count of completed documents          |
| `cancelled`   | number | All-time count of voided documents             |
| `declined`    | number | All-time count of declined documents           |

### Example Object

```json
{
  "period": {
    "from": "2024-01-01T00:00:00.000Z",
    "to": "2024-01-31T23:59:59.999Z"
  },
  "documents": {
    "total_created": 42,
    "total_sent": 38,
    "total_completed": 31,
    "total_cancelled": 4,
    "total_declined": 2,
    "completion_rate": 84,
    "median_signing_hours": 18.5
  },
  "workspace_snapshot": {
    "draft": 7,
    "sent": 12,
    "in_progress": 3,
    "completed": 201,
    "cancelled": 14,
    "declined": 5
  }
}
```

## Get Analytics

Retrieve document metrics and workspace totals for a date range.

### Endpoint

```
GET /api/v1/analytics
```

### Required Scope

`seal:documents:read`

### Query Parameters

| Parameter | Type   | Description                                                        |
| --------- | ------ | ------------------------------------------------------------------ |
| `from`    | number | Unix timestamp in **milliseconds** — start of the reporting period |
| `to`      | number | Unix timestamp in **milliseconds** — end of the reporting period   |

> **Info**
>
> If `from` and `to` are omitted, the endpoint defaults to the **last 30 days**.
> The `workspace_snapshot` is always a current point-in-time count, regardless
> of the date range.

### TypeScript Example

```typescript
// Analytics for January 2024
const from = new Date("2024-01-01").getTime();
const to = new Date("2024-02-01").getTime();

const response = await fetch(
  `https://api.seal.nyc/api/v1/analytics?from=${from}&to=${to}`,
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  }
);

const analytics = await response.json();

console.log(`Completion rate: ${analytics.documents.completion_rate}%`);
console.log(
  `Median signing time: ${analytics.documents.median_signing_hours}h`
);
```

### cURL Example

```bash
# Last 30 days (default)
curl -X GET "https://api.seal.nyc/api/v1/analytics" \
  -H "Authorization: Bearer ak_your_api_key_here"

# Specific date range (Unix timestamps in milliseconds)
curl -X GET "https://api.seal.nyc/api/v1/analytics?from=1704067200000&to=1706745600000" \
  -H "Authorization: Bearer ak_your_api_key_here"
```

### Response

```json
{
  "period": {
    "from": "2024-01-01T00:00:00.000Z",
    "to": "2024-02-01T00:00:00.000Z"
  },
  "documents": {
    "total_created": 42,
    "total_sent": 38,
    "total_completed": 31,
    "total_cancelled": 4,
    "total_declined": 2,
    "completion_rate": 84,
    "median_signing_hours": 18.5
  },
  "workspace_snapshot": {
    "draft": 7,
    "sent": 12,
    "in_progress": 3,
    "completed": 201,
    "cancelled": 14,
    "declined": 5
  }
}
```

### Dashboard Integration Example

```typescript
// Pull monthly analytics for the last 12 months
async function getMonthlyAnalytics() {
  const months = [];

  for (let i = 11; i >= 0; i--) {
    const start = new Date();
    start.setMonth(start.getMonth() - i, 1);
    start.setHours(0, 0, 0, 0);

    const end = new Date(start);
    end.setMonth(end.getMonth() + 1);

    const response = await fetch(
      `https://api.seal.nyc/api/v1/analytics?from=${start.getTime()}&to=${end.getTime()}`,
      { headers: { Authorization: "Bearer ak_your_api_key_here" } }
    );

    const data = await response.json();
    months.push({
      month: start.toLocaleString("default", {
        month: "short",
        year: "numeric",
      }),
      completed: data.documents.total_completed,
      completion_rate: data.documents.completion_rate,
    });
  }

  return months;
}
```

## Next Steps

- **[Documents API](/docs/api-reference/documents)** - Manage individual documents
- **[Audit Log API](/docs/api-reference/audit-log)** - Full tamper-evident activity history
- **[Webhooks](/docs/webhooks)** - Real-time event notifications