Skip to main content

Usage Log

Audit every AI call your account makes: a per-request usage log with operation type, model, token counts, and cost estimates via GET /v1/credits/usage/log.

The usage log endpoint (GET /v1/credits/usage/log) returns a detailed log of individual API requests with per-request token counts, model information, and cost estimates. It is the most granular usage view available, showing every LLM call and OCR request made by your account, ordered by most recent first.

Each log entry links back to the originating document (when applicable) via the document_id field, allowing you to trace costs to specific documents in your pipeline. Use the log when the aggregated views are not enough: auditing a billing period, investigating a cost spike the Usage Summary surfaced, or verifying that prompt caching is working via the cache_read_tokens column.

The usage log is ordered by most recent first. Use page-based pagination (page and limit, max 100 per page) to browse historical entries.
GET/v1/credits/usage/log

Query parameters

pageintegerPage number (default 1).
limitintegerMax items per page (default 20, max 100).

cURL — Most recent usage log entries

curl "https://api.talonic.com/v1/credits/usage/log?page=1&limit=20" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

itemsarrayArray of per-request usage log entries.
items[].idstringLog entry UUID.
items[].modelstringModel used for this request.
items[].input_tokensintegerInput tokens consumed.
items[].output_tokensintegerOutput tokens produced.
items[].cache_read_tokensintegerPrompt cache read tokens.
items[].cost_estimate_usdnumberEstimated cost in USD.
items[].operation_typestringOperation category (e.g. extraction, matching).
items[].document_idstring | nullAssociated document UUID if applicable.
items[].created_atstringISO 8601 timestamp of the request.
totalintegerTotal number of log entries.
pageintegerCurrent page number.
limitintegerItems per page.

Response

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model": "claude-sonnet-4-5",
      "input_tokens": 4280,
      "output_tokens": 612,
      "cache_read_tokens": 0,
      "cost_estimate_usd": 0.022,
      "operation_type": "extraction",
      "document_id": "doc-uuid-abc123",
      "created_at": "2026-06-14T10:32:00.000Z"
    }
  ],
  "total": 8240,
  "page": 1,
  "limit": 20
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What are cache_read_tokens?+
Cache read tokens represent prompt cache hits where previously cached input was reused instead of being reprocessed. These are charged at a significantly lower rate than regular input tokens.
Why is document_id null for some entries?+
Operations that are not tied to a specific document (e.g. schema generation, field resolution) have a null `document_id`. Document-level operations like extraction always include the document reference.
Can I filter the usage log by document?+
The log endpoint itself takes only pagination parameters. To see every AI operation for one specific document, call `GET /v1/usage/documents/:id`, which returns the per-document breakdown with totals in a single request.

Related

Usage Summary by Operation
Credit Balance
Per-Document Usage