Start a signal summary export

POST

https://api.agentpaid.io/api/v2/signals/summary/batch/

POST

/api/v2/signals/summary/batch/

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.signals.createSignalSummaryExport({
        from: "2025-09-01",
        to: "2026-09-01",
    });
}
main();

{
  "id": "sse_5pZa1Kd8Nqx",
  "status": "pending",
  "spec": {
    "name": "string",
    "signalNames": [
      {
        "name": "string",
        "group": "workflow_run",
        "slug": "runs"
      }
    ],
    "measures": [
      {
        "fn": "count",
        "path": "steps",
        "slug": "string"
      }
    ],
    "interval": "month",
    "dimensions": [
      {
        "kind": "presence",
        "path": "steps",
        "appliesTo": [
          "string"
        ],
        "values": {
          "true": {
            "group": "string",
            "slug": "string"
          },
          "false": {
            "group": "string",
            "slug": "string"
          }
        }
      }
    ],
    "columnNameTemplate": "{dim1}_{signal}_{dim2}"
  },
  "columns": [
    {
      "name": "ticket_runs_1_step",
      "signalGroup": "string",
      "dimensionGroup": "string"
    }
  ],
  "format": "json",
  "from": "2025-09-01",
  "to": "2026-09-01",
  "rowCount": 1,
  "downloadUrl": "string",
  "expiresAt": "2024-01-15T09:30:00Z",
  "error": "string",
  "createdAt": "2024-01-15T09:30:00Z",
  "completedAt": "2024-01-15T09:30:00Z"
}

Produces a usage summary file: one row per customer per month, with columns broken down by the signal payload fields you name. Choose format to get JSON or a wide CSV; JSON is the default. The export runs in the background, so this returns immediately with a pending export and the file appears on it once it succeeds. Give spec to describe the columns, or copyFrom with an earlier export’s id to reuse that export’s columns over a new window. The spec is stored on the export, so an old file can always be explained by the export that produced it. Signals are bucketed by month in UTC on their effective timestamp, the same basis billing uses, so the totals reconcile with invoices. One export runs per organization at a time.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Request

Body

fromstringRequiredformat: "^\d{4}-\d{2}-\d{2}$"

Start of the window, inclusive, snapped down to a period start. Cannot be earlier than 2025-09-01.

tostringRequiredformat: "^\d{4}-\d{2}-\d{2}$"

End of the window, exclusive, snapped down to a period start.

specobjectOptional

The shape of the file: which signals to count, how to break them down, and what each column is called. Required unless copyFrom is given.

copyFromstringOptional>=1 character

Reuse the shape of an earlier export, so a monthly run produces the same columns without restating them. Give this or spec, not both.

customerIdslist of stringsOptional

Restrict the file to these customers. Accepts Paid IDs, UUIDs, or your external IDs. Omit for every customer.

formatenumOptionalDefaults to json

Format of the produced file. json gives the columns and one object per customer per month; csv gives the wide spreadsheet with three header rows.

Allowed values:

Response

202

idstring

statusenum

Allowed values:

specobject

The shape this export ran, stored here so the file stays explainable. Pass this export's id as copyFrom to reproduce its columns.

columnslist of objects

Columns in the file, in order.

formatenum

Format this export's file was written in.

Allowed values:

fromstring

tostring

rowCountinteger or null

downloadUrlstring or null

Short-lived download link, present only while the export is succeeded and unexpired. A new link is issued each time this export is fetched.

expiresAtdatetime or null

When the stored file stops being downloadable.

errorstring or null

Why the export failed, or null.

createdAtdatetime

completedAtdatetime or null

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error