API referenceContracts
Report usage
POST
Up to 500 usage records in one call, all or none. Each external_ref is stored once — the answer counts what was recorded and what was a duplicate, so a retry is safe. Usage before usage_open_from belongs to a period already billed and is refused. Scope partner:usage:write; a metering service needs no other.
apiKey partner:usage:writeheader
AuthorizationBearer <ab_…>An API key from Integrations → Connect AI assistants (MCP) → New access, bound to exactly one company. Each operation names the scope the key must carry.
Scope: partner:usage:write
source*SourceMatch
^[a-z0-9][a-z0-9_-]{0,49}$external_ref*External RefMatch
^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,254}$AlphaCount-Version?stringThe API version to use. Default: the current one.
application/json- body
records*array<>Items
1 <= items <= 500OK
application/json- response
duplicates*DuplicatesRecords whose external_ref was known already; not stored again.
recorded*Recordedcurl -X POST 'https://app.alphacount.ai/api/partner/v1/contracts/by-ref/string/string/usage' \ -H 'Authorization: Bearer ab_...' \ -H 'Content-Type: application/json' \ -d '{ "records": [ { "external_ref": "u-1", "item_ref": "tokens", "occurred_on": "2026-01-10", "quantity": 1500 }, { "external_ref": "u-2", "item_ref": "tokens", "occurred_on": "2026-01-20", "quantity": 500 }, { "external_ref": "u-2", "item_ref": "tokens", "occurred_on": "2026-01-20", "quantity": 500 } ]}'Example Response
{ "duplicates": 1, "recorded": 2}