Credit usage

List the credit movements of your workspace, newest first, over the whole history or a period you choose.

Returns the credit movements of your workspace, one entry per movement, newest first. Each entry says when it happened, which product or signal it was for, how many credits it was and what became of them. Use it to understand what your credits are spent on, or to pull your consumption into your own tools.

To check how many credits you have left, read your balance instead with GET /api/v3/credits/balance.

Route

GET/api/v3/usage

Access modes

Use a workspace API key. The workspace is inferred from the key, and you only ever see your own workspace's usage.

Authorization: Bearer sk_live_...

Query parameters

Parameter	Type	Description
date_from	string	ISO 8601 date or timestamp. Includes credit movements at or after this moment. Optional, without lower bound by default.
date_to	string	ISO 8601 date or timestamp. Includes credit movements strictly before this moment. Optional, without upper bound by default.
cursor	string	Opaque pagination token from the previous response (`meta.cursor.next`). Omit it for the first page. Keep the same dates while paginating.
limit	integer	Number of entries per page, from 1 to 100. Defaults to 25.

date_from and date_to are optional filters, and you can use either one on its own. The period covers date_from up to, but not including, date_to. With neither, you get your whole history, starting from the most recent entry.

All dates are in UTC.

The list is cursor-paginated: each response includes meta.cursor.next. Pass it back as cursor, with the same date_from and date_to, to fetch the next page, until meta.cursor.has_more is false. Treat the cursor as an opaque value and do not build or edit it yourself.

Example request

curl "https://api.getsillage.com/api/v3/usage?date_from=2026-08-01&date_to=2026-08-15&limit=25" \
  -H "Authorization: Bearer $SILLAGE_API_KEY"

Success response

Status: 200 OK

{
  "data": [
    {
      "id": 48213,
      "created_at": "2026-08-12T09:41:07.000Z",
      "status": "captured",
      "product": "discovery_standard",
      "signal_template_key": "mentioned-keywords-on-linkedin",
      "credits": 20
    },
    {
      "id": 48102,
      "created_at": "2026-08-11T14:03:55.000Z",
      "status": "held",
      "product": "account_monitoring",
      "signal_template_key": null,
      "credits": 5
    },
    {
      "id": 47990,
      "created_at": "2026-08-09T16:20:31.000Z",
      "status": "released",
      "product": "discovery_standard",
      "signal_template_key": "mentioned-keywords-on-linkedin",
      "credits": 3
    }
  ],
  "meta": {
    "cursor": {
      "next": null,
      "has_more": false
    }
  }
}

When nothing matches, data is an empty array and meta.cursor.has_more is false.

Response fields

Field	Type	Description
data[].id	integer	ID of the credit movement. Specific to your environment.
data[].created_at	string	When the credit movement was recorded, in ISO 8601.
data[].status	string	Where these credits are in their life: `held`, `captured` or `released`. See below.
data[].product	string	What was charged for, such as `account_monitoring` or `discovery_standard`. The list is open: a new product can appear without notice.
data[].signal_template_key	string or null	The signal that produced this consumption, or `null` when it does not come from a signal. See below.
data[].credits	number	Amount of credits, never rounded.
meta.cursor.next	string or null	Pass it as `cursor` to fetch the next page. `null` when there is no next page.
meta.cursor.has_more	boolean	`true` when more entries exist after this page, `false` on the last page.

Entries are sorted from the newest to the oldest. Entries recorded at the same moment keep a stable order, so no entry is skipped or repeated from one page to the next.

To read every entry, keep the same dates, send meta.cursor.next as cursor and repeat until meta.cursor.has_more is false.

Credit statuses

status tells where the credits are in their life:

held: reserved for an action still in progress. These credits are already taken off your balance, but the charge is not final yet.
captured: the action completed and the credits are spent.
released: the reservation was cancelled because the action did not complete, and the credits went back to your balance. You are not charged for them.

To see what your workspace has spent, add up the credits of the entries whose status is held or captured, and leave released out.

Signals

When signal_template_key is set, it is the key of that signal in List signal templates, so you can match the two. It is null for consumption with no signal to attribute it to, and for consumption from a signal that can no longer be matched to a signal in your catalog. In both cases, product tells what was charged for.

Errors

Status	Meaning
400	`date_from` is after `date_to`, or `cursor` or `limit` is invalid.
401	The API key is missing or invalid.
429	Rate limit exceeded.
500	An unexpected server error occurred.

Error responses use RFC 9457 problem documents with Content-Type: application/problem+json. type is always about:blank on v3, and errors names the parameter at fault.

A limit above 100, a cursor that is not valid, or a date_from after date_to, is refused with 400. For example, with limit=500:

{
  "type": "about:blank",
  "title": "Invalid query parameters",
  "status": 400,
  "instance": "/api/v3/usage",
  "errors": {
    "limit": ["Too big: expected number to be <=100"]
  }
}

Credit usage

On this page