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

{
  "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

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

// 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://seal.convex.site/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

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

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

Response

{
  "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

// 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://seal.convex.site/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 - Manage individual documents
Audit Log API - Full tamper-evident activity history
Webhooks - Real-time event notifications

Analytics API

On this page