List usage
List the credit movements of the client's workspace, newest first, over the whole history or a period you choose.
Returns the credit movements of the client's workspace, one entry per movement, newest first, 25 entries per page by default: set limit (up to 100) to get more or fewer. Each entry says when it happened, what the credits paid for, how many credits it was and where it stands on your invoice. Use it to see what you are billed for this client, or to pull it into your own tools.
Same request as the client API GET /api/v3/usage, resolved for the client named by partner_workspace_id instead of an API key. Only the finished charges billed to you are listed.
Route
Path parameters
| Parameter | Type | Description |
|---|---|---|
| partner_workspace_id | string | Your own ID for the client workspace, as you chose it at creation. URL-encode it in the path. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
| created_at_from | string | Only credit movements created at or after this moment. ISO 8601 date and time with a UTC offset, for example 2026-09-01T00:00:00Z. A date without a time is refused with 422. Both bounds are included. Optional, without lower bound by default. |
| created_at_to | string | Only credit movements created at or before this moment. ISO 8601 date and time with a UTC offset, for example 2026-09-01T00:00:00Z. A date without a time is refused with 422. Both bounds are included. Optional, without upper bound by default. It must not be before created_at_from. |
| cursor | string | The meta.cursor.next of the previous response, to fetch the next page. Omit it for the first page. It only works with the dates it was issued for: reused with other dates, or sent empty, it is refused with 422. See Pagination. |
| limit | integer | Number of entries per page, from 1 to 100. Defaults to 25. |
Each date is optional and you can use either one on its own. Both moments are included in the period. With neither, you get the client's whole history, starting from the most recent entry. A parameter that is not listed is refused with 422.
Entries are sorted from the newest to the oldest.
Example request
curl "https://api.getsillage.com/api/v3/partner/workspaces/ws_123/usage?created_at_from=2026-08-01T00:00:00Z&created_at_to=2026-08-15T23:59:59Z&limit=25" \
-H "Authorization: Bearer $SILLAGE_MASTER_KEY"Success response
Status: 200 OK
{
"data": [
{
"id": 48213,
"created_at": "2026-08-12T09:41:07.000Z",
"status": "to_invoice",
"credits": 20,
"product": {
"scope": "discovery",
"signal_bucket": null,
"signal_template_key": "mentioned-keywords-on-linkedin",
"signal_template_id": 4,
"signal_setup_id": 31,
"company_id": 1207,
"persona_id": 12
}
},
{
"id": 48102,
"created_at": "2026-08-11T14:03:55.000Z",
"status": "invoiced",
"credits": 50,
"product": {
"scope": "account_monitoring",
"signal_bucket": "essential",
"signal_template_key": null,
"signal_template_id": null,
"signal_setup_id": null,
"company_id": 1207,
"persona_id": 12
}
},
{
"id": 47990,
"created_at": "2026-08-09T16:20:31.000Z",
"status": "paid",
"credits": 20,
"product": {
"scope": "discovery",
"signal_bucket": null,
"signal_template_key": "mentioned-keywords-on-linkedin",
"signal_template_id": 4,
"signal_setup_id": 31,
"company_id": 1342,
"persona_id": 12
}
}
],
"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. |
| data[].created_at | string | When the credit movement was recorded, in ISO 8601. |
| data[].status | string | Where the charge stands on your invoice: to_invoice, invoiced or paid. See Invoice statuses. |
| data[].credits | number | Amount of credits, never rounded. |
| data[].product | object | What the credits paid for. Every key below is always present, and is null when it does not apply to the entry. See What an entry paid for. |
| data[].product.scope | string | discovery for a signal found by one of the signal setups, account_monitoring for the monitoring of an account. |
| data[].product.signal_bucket | string or null | The monitoring that was paid for, as in the monitoring price of List a client's signal templates. null on a discovery entry. |
| data[].product.signal_template_key | string or null | The key of the signal template that found the signal, as returned by List a client's signal templates. null on an account_monitoring entry. |
| data[].product.signal_template_id | integer or null | The id of the signal template that found the signal, as returned by List a client's signal templates. null on an account_monitoring entry, and when the signal no longer exists. |
| data[].product.signal_setup_id | integer or null | ID of the signal setup that found the signal. null on an account_monitoring entry, and when that signal setup no longer exists. |
| data[].product.company_id | integer or null | The company the credits were spent on, as its ID in the client's workspace. |
| data[].product.persona_id | integer or null | The persona the signal setup or the monitoring was for. null when it had none. |
| 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. |
To read every entry, send meta.cursor.next as cursor, and repeat until meta.cursor.has_more is false.
Invoice statuses
status tells where the charge stands on your invoice:
to_invoice: the charge is final and not invoiced yet.invoiced: it is included in an invoice sent to you.paid: that invoice is paid.
Only finished charges are listed, so reserved credits and cancelled reservations never appear. What you are invoiced for is the sum of the credits of the entries.
What an entry paid for
product.scope tells which of the two it is:
discovery: a signal found by one of the client's signal setups.signal_template_key,signal_template_idandsignal_setup_idname the signal template and the signal setup that found it,company_idthe company it was found on andpersona_idthe persona the signal setup is for.signal_bucketisnull.account_monitoring: the monitoring of one account for one month.signal_buckettells which monitoring was paid for,company_idthe account in the client's workspace andpersona_idthe persona it was paid for.signal_template_key,signal_template_idandsignal_setup_idarenull.
If a signal is deleted, the entry that paid for it stays in the list, with signal_template_key, signal_template_id, signal_setup_id, company_id and persona_id set to null. If a signal setup is deleted, only signal_setup_id becomes null.
Errors
| Status | Meaning |
|---|---|
| 401 | The master key is missing or invalid. |
| 404 | No workspace found for this partner_workspace_id. |
| 422 | A date is not valid or has no time, created_at_from is after created_at_to (code invalid_date_range, errors.created_at_from says "must be on or before created_at_to"), limit is outside 1 to 100, a parameter is not known (the error names it), or cursor was not issued to you by this endpoint, was issued for other dates, or is empty. |
| 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; code tells one problem from another, detail says what went wrong this time, and errors names the field at fault. For example, with limit=500:
{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"code": "invalid_query",
"detail": "Invalid query parameters",
"instance": "/api/v3/partner/workspaces/ws_123/usage",
"errors": {
"limit": ["must be at most 100"]
}
}