/api/gateway/usage/importImport historical local usage
Attributes per-turn token counts from local Codex or Claude Code logs (metadata only) to your organization, priced at current catalog list rates. Never charged and never deducted from credits. Idempotent per record identity; unknown models are kept at zero cost and listed in unmatched_models.
Authentication: Bearer API key in the Authorization header
Request body
batch_idstringrequiredGroups the run; replaying the same records inserts nothing.
recordsarray<object>requiredrecords
modelstringrequiredModel id as the local log names it.
input_tokensintegerrequiredFresh (non-cached) input.
output_tokensintegerrequiredOutput including reasoning.
cached_tokensintegerCached input.
reasoning_tokensintegerReasoning subset of output, for display.
timestampstringrequiredISO 8601 turn time; naive values read as UTC.
sourceenumrequiredevent_idstring | nullThe log's stable per-turn id, folded into the dedupe hash.
org_idstring | nullIgnored for API keys: a key always imports into its own organization.
Responses
201Imported.
Response
batch_idstringrequiredreceivedintegerrequiredimportedintegerrequiredNewly inserted records.
duplicatesintegerrequiredRecords already imported before.
unmatched_modelsarray<string>requiredby_modelarray<object>requiredThe organization's whole imported attribution after this batch.
by_model
sourceenumrequiredmodelstringrequiredCatalog slug when matched, else the raw model id.
model_matchedbooleanrequiredFalse when the model is outside the catalog (priced at 0).
request_countintegerrequiredinput_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredcost_usdnumberrequiredHistorical attribution at current list rates, dollars. Never charged.
totalsobjectrequiredtotals
request_countintegerrequiredinput_tokensintegerrequiredoutput_tokensintegerrequiredcost_usdnumberrequiredDollars, attribution only.
400Empty batch, more than 10,000 records, or a bad timestamp.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
401Missing, unknown or revoked API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
403Not called with an organization API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
422The body or query failed validation.
Response
detailarray<object>requireddetail
typestringlocarray<string | integer>msgstring
Request
curl -X POST https://api.experientiallabs.ai/api/gateway/usage/import \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_id": "laptop-2026-11-18",
"records": [
{
"model": "claude-sonnet-4-6",
"input_tokens": 1840,
"output_tokens": 622,
"cached_tokens": 41200,
"reasoning_tokens": 0,
"timestamp": "2026-11-12T18:04:11Z",
"source": "claude-code",
"event_id": "msg_01Hq8Xc2"
},
{
"model": "gpt-5.5-codex",
"input_tokens": 3120,
"output_tokens": 904,
"cached_tokens": 12800,
"reasoning_tokens": 512,
"timestamp": "2026-11-13T09:41:52Z",
"source": "codex",
"event_id": "sess-7f2a:14"
}
]
}'Response
{
"batch_id": "laptop-2026-11-18",
"received": 2,
"imported": 2,
"duplicates": 0,
"unmatched_models": [],
"by_model": [
{
"source": "claude-code",
"model": "claude-sonnet-4.6",
"model_matched": true,
"request_count": 1,
"input_tokens": 1840,
"output_tokens": 622,
"cached_input_tokens": 41200,
"reasoning_tokens": 0,
"cost_usd": 0.027
},
{
"source": "codex",
"model": "gpt-5.5-codex",
"model_matched": true,
"request_count": 1,
"input_tokens": 3120,
"output_tokens": 904,
"cached_input_tokens": 12800,
"reasoning_tokens": 512,
"cost_usd": 0.0167
}
],
"totals": {
"request_count": 2,
"input_tokens": 4960,
"output_tokens": 1526,
"cost_usd": 0.0437
}
}https://api.experientiallabs.ai/api/gateway/usage/import