POST/api/gateway/usage/import

Import 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_idstringrequired

    Groups the run; replaying the same records inserts nothing.

  • recordsarray<object>required
    records
    • modelstringrequired

      Model id as the local log names it.

    • input_tokensintegerrequired

      Fresh (non-cached) input.

    • output_tokensintegerrequired

      Output including reasoning.

    • cached_tokensinteger

      Cached input.

      Default: 0
    • reasoning_tokensinteger

      Reasoning subset of output, for display.

      Default: 0
    • timestampstringrequired

      ISO 8601 turn time; naive values read as UTC.

    • sourceenumrequired
      "codex""claude-code"
    • event_idstring | null

      The log's stable per-turn id, folded into the dedupe hash.

  • org_idstring | null

    Ignored for API keys: a key always imports into its own organization.

Responses

  • 201

    Imported.

    Response
    • batch_idstringrequired
    • receivedintegerrequired
    • importedintegerrequired

      Newly inserted records.

    • duplicatesintegerrequired

      Records already imported before.

    • unmatched_modelsarray<string>required
    • by_modelarray<object>required

      The organization's whole imported attribution after this batch.

      by_model
      • sourceenumrequired
        "codex""claude-code"
      • modelstringrequired

        Catalog slug when matched, else the raw model id.

      • model_matchedbooleanrequired

        False when the model is outside the catalog (priced at 0).

      • request_countintegerrequired
      • input_tokensintegerrequired
      • output_tokensintegerrequired
      • cached_input_tokensintegerrequired
      • reasoning_tokensintegerrequired
      • cost_usdnumberrequired

        Historical attribution at current list rates, dollars. Never charged.

    • totalsobjectrequired
      totals
      • request_countintegerrequired
      • input_tokensintegerrequired
      • output_tokensintegerrequired
      • cost_usdnumberrequired

        Dollars, attribution only.

  • 400

    Empty batch, more than 10,000 records, or a bad timestamp.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 401

    Missing, unknown or revoked API key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    Not called with an organization API key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    The body or query failed validation.

    Response
    • detailarray<object>required
      detail
      • typestring
      • locarray<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