SparQDocs
GuidesAPI referencesparqhq.ai
API referenceObservability

Usage Report

GET
/v1/admin/usage/report

Usage grouped by up to three dimensions. Client admins see only their own client.

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Bearer credential. API keys look like sqk_<geo>_<key_id>_<secret>: treat them as opaque and never put one in a browser. Older keys without the geo part stay valid until rotated. Find a geo's endpoints through GET /.well-known/sparq-discovery before sending a key.

Query Parameters

group_by*array<>
Items1 <= items <= 3
since?|null
until?|null
project_id?|null
audience_tenant_id?|

Client showback.

Header Parameters

Sparq-Workspace?string

For a person signed in to a console with several workspaces: the workspace this call is for, one of their memberships (listMyMemberships). Without it such a person gets workspace_required (400); a workspace they are not a member of is forbidden. It never grants anything, and other callers' credentials ignore it.

Formatuuid

Response Body

Successful Response

application/json
  1. response

Grouped usage. Rows add up to totals, which equals the ledger for the same filters.

group_by*array<>
since*Since
Formatdate-time
until*Until
Formatdate-time
rows*array<>
totals*
as_of?|

When the report was made.

coverage?array<>

The sources (stamps) the report read.

missing?array<>

Sources it could not read, and why.

complete?Complete

False if any source is missing: the totals are partial.

Defaulttrue
Example Request
curl -X GET 'http://dev-sparq.centralindia.cloudapp.azure.com:8000/v1/admin/usage/report?group_by=audience_tenant'
Example Response
{  "group_by": [    "audience_tenant"  ],  "since": "2019-08-24T14:15:22Z",  "until": "2019-08-24T14:15:22Z",  "rows": [    {      "keys": {        "property1": "string",        "property2": "string"      },      "totals": {        "calls": 0,        "input_tokens": 0,        "output_tokens": 0,        "cached_tokens": 0,        "reasoning_tokens": 0,        "estimated_cost_usd": "string",        "billed_cost_usd": "string",        "effective_cost_usd": "string"      }    }  ],  "totals": {    "calls": 0,    "input_tokens": 0,    "output_tokens": 0,    "cached_tokens": 0,    "reasoning_tokens": 0,    "estimated_cost_usd": "string",    "billed_cost_usd": "string",    "effective_cost_usd": "string"  },  "as_of": "2019-08-24T14:15:22Z",  "coverage": [    {      "source": "string",      "as_of": "2019-08-24T14:15:22Z"    }  ],  "missing": [    {      "source": "string",      "reason": "string"    }  ],  "complete": true}

Run Destination Test POST

> **Not available yet.** This operation is part of the published contract and answers `501 not_implemented` until it is built. The request and response shapes below are final for this contract version.

Export Audit POST

> **Not available yet.** This operation is part of the published contract and answers `501 not_implemented` until it is built. The request and response shapes below are final for this contract version. The audit log for a window, complete or failed as `incomplete`, never partial.