POST/api/orgs/{org_id}/spend/view

Read a report and its chart

Body is a frozen SpendQuery with its registered as_of and snapshot_id. Returns the report and the selected dimension's series at that snapshot; never starts new work. 409 snapshot_invalidated means report and chart no longer match. API keys need provisioning strength and scope: org.

Authentication: Bearer API key in the Authorization header

Path parameters

  • org_idstringrequired

    Your organization id (uuid). GET /api/whoami returns it.

Request body

  • startstringrequired

    Inclusive start, with a UTC offset.

  • endstringrequired

    Exclusive end, with a UTC offset. Must be after start.

  • time_zonestring

    IANA zone for day and month buckets.

    Default: "UTC"
  • scopeany
    Default: "org"
  • basisany
    Default: "requests"
  • group_byany
    Default: "model"
  • tag_keystring | null

    Required exactly when group_by is tag.

    Default: null
  • grainany
    Default: "day"
  • filtersarray<object>

    At most one filter per dimension.

    Default: []
    filters
    • dimensionenumrequired

      Grouping and filter dimension. key and member values are uuids. tag is only a group_by (with tag_key); filter tags through tags.

      "model""key""member""end_user""provider""funding""surface""outcome""error""app""prompt""tag""source"
    • valuesarray<string>
      Default: []
    • missingboolean

      Also match calls with no value for this dimension.

      Default: false
    • excludeboolean

      Invert the predicate. Must be a JSON boolean.

      Default: false
  • tagsarray<object>

    At most one predicate per tag key.

    Default: []
    tags
    • keystringrequired
    • valuesarray<string>
      Default: []
    • missingboolean

      Also match calls without this tag key.

      Default: false
    • excludeboolean
      Default: false
  • sortany
    Default: "spend"
  • directionenum
    "asc""desc"
    Default: "desc"
  • offsetinteger
    Default: 0
  • limitinteger
    Default: 50
  • as_ofstring | null

    Report cutoff. Server-set on the first read; not in the future and not before start.

    Default: null
  • snapshot_idstring

    Registered snapshot token. Requires its original as_of. Omitted from responses when unset.

Responses

  • 200

    OK

    Response
    • reportobjectrequired

      Summary, chart buckets and a page of the breakdown for one frozen query. query is the frozen query to send back for the next page (offset: next_offset).

      report
      • queryobjectrequired

        A bounded report slice. end is exclusive; the range is at most ten years. Omit as_of and snapshot_id for a fresh read; the response returns them frozen, and later reads (pagination, view, series, facets, activity, export) send them back unchanged so every panel reads one snapshot.

        query
        • startstringrequired

          Inclusive start, with a UTC offset.

        • endstringrequired

          Exclusive end, with a UTC offset. Must be after start.

        • time_zonestring

          IANA zone for day and month buckets.

          Default: "UTC"
        • scopeany
          Default: "org"
        • basisany
          Default: "requests"
        • group_byany
          Default: "model"
        • tag_keystring | null

          Required exactly when group_by is tag.

          Default: null
        • grainany
          Default: "day"
        • filtersarray<object>

          At most one filter per dimension.

          Default: []
          filters
          • dimensionenumrequired

            Grouping and filter dimension. key and member values are uuids. tag is only a group_by (with tag_key); filter tags through tags.

            "model""key""member""end_user""provider""funding""surface""outcome""error""app""prompt""tag""source"
          • valuesarray<string>
            Default: []
          • missingboolean

            Also match calls with no value for this dimension.

            Default: false
          • excludeboolean

            Invert the predicate. Must be a JSON boolean.

            Default: false
        • tagsarray<object>

          At most one predicate per tag key.

          Default: []
          tags
          • keystringrequired
          • valuesarray<string>
            Default: []
          • missingboolean

            Also match calls without this tag key.

            Default: false
          • excludeboolean
            Default: false
        • sortany
          Default: "spend"
        • directionenum
          "asc""desc"
          Default: "desc"
        • offsetinteger
          Default: 0
        • limitinteger
          Default: 50
        • as_ofstring | null

          Report cutoff. Server-set on the first read; not in the future and not before start.

          Default: null
        • snapshot_idstring

          Registered snapshot token. Requires its original as_of. Omitted from responses when unset.

      • totalsobjectrequired

        Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

        totals
        • countintegerrequired

          Settled requests (or terminal attempts on the attempts basis); not a success count.

        • rejected_countintegerrequired

          Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

        • errorsintegerrequired

          Non-completed requests or attempts, rejections included.

        • input_tokensintegerrequired
        • output_tokensintegerrequired
        • cached_input_tokensintegerrequired
        • reasoning_tokensintegerrequired
        • paid_nano_usdstringrequired

          Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

        • byok_nano_usdstringrequired

          Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

        • free_nano_usdstringrequired

          Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

        • unknown_usage_countintegerrequired

          Usage whose provider accounting is unknown. Nonzero makes the money provisional.

      • bucketsarray<object>required
        buckets
        • startstringrequired
        • figuresobjectrequired

          Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

          figures
          • countintegerrequired

            Settled requests (or terminal attempts on the attempts basis); not a success count.

          • rejected_countintegerrequired

            Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

          • errorsintegerrequired

            Non-completed requests or attempts, rejections included.

          • input_tokensintegerrequired
          • output_tokensintegerrequired
          • cached_input_tokensintegerrequired
          • reasoning_tokensintegerrequired
          • paid_nano_usdstringrequired

            Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • byok_nano_usdstringrequired

            Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • free_nano_usdstringrequired

            Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • unknown_usage_countintegerrequired

            Usage whose provider accounting is unknown. Nonzero makes the money provisional.

      • groupsarray<object>required
        groups
        • valuestring | nullrequired
        • labelstring | nullrequired
        • figuresobjectrequired

          Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

          figures
          • countintegerrequired

            Settled requests (or terminal attempts on the attempts basis); not a success count.

          • rejected_countintegerrequired

            Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

          • errorsintegerrequired

            Non-completed requests or attempts, rejections included.

          • input_tokensintegerrequired
          • output_tokensintegerrequired
          • cached_input_tokensintegerrequired
          • reasoning_tokensintegerrequired
          • paid_nano_usdstringrequired

            Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • byok_nano_usdstringrequired

            Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • free_nano_usdstringrequired

            Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • unknown_usage_countintegerrequired

            Usage whose provider accounting is unknown. Nonzero makes the money provisional.

      • filter_labelsarray<object>
        Default: []
        filter_labels
        • valuestring | nullrequired
        • labelstringrequired
        • dimensionenumrequired

          Grouping and filter dimension. key and member values are uuids. tag is only a group_by (with tag_key); filter tags through tags.

          "model""key""member""end_user""provider""funding""surface""outcome""error""app""prompt""tag""source"
        • tag_keystring | null
          Default: null
      • group_countintegerrequired
      • next_offsetinteger | null

        Null on the last page.

      • coverageobjectrequired

        Projection freshness, independent of whether the slice is empty.

        coverage
        • as_ofstringrequired
        • projected_throughstring | nullrequired
        • completebooleanrequired
        • pending_requestsintegerrequired
        • includes_pre_admission_rejectionsboolean
          Default: false
    • seriesobjectrequired
      One of

      object

      • statusanyrequired
      • dataobjectrequired

        Up to seven spend-ranked values of the query's group_by plus the remainder, stacked per bucket.

        data
        • queryobjectrequired

          A bounded report slice. end is exclusive; the range is at most ten years. Omit as_of and snapshot_id for a fresh read; the response returns them frozen, and later reads (pagination, view, series, facets, activity, export) send them back unchanged so every panel reads one snapshot.

          query
          • startstringrequired

            Inclusive start, with a UTC offset.

          • endstringrequired

            Exclusive end, with a UTC offset. Must be after start.

          • time_zonestring

            IANA zone for day and month buckets.

            Default: "UTC"
          • scopeany
            Default: "org"
          • basisany
            Default: "requests"
          • group_byany
            Default: "model"
          • tag_keystring | null

            Required exactly when group_by is tag.

            Default: null
          • grainany
            Default: "day"
          • filtersarray<object>

            At most one filter per dimension.

            Default: []
            filters
            • dimensionenumrequired

              Grouping and filter dimension. key and member values are uuids. tag is only a group_by (with tag_key); filter tags through tags.

              "model""key""member""end_user""provider""funding""surface""outcome""error""app""prompt""tag""source"
            • valuesarray<string>
              Default: []
            • missingboolean

              Also match calls with no value for this dimension.

              Default: false
            • excludeboolean

              Invert the predicate. Must be a JSON boolean.

              Default: false
          • tagsarray<object>

            At most one predicate per tag key.

            Default: []
            tags
            • keystringrequired
            • valuesarray<string>
              Default: []
            • missingboolean

              Also match calls without this tag key.

              Default: false
            • excludeboolean
              Default: false
          • sortany
            Default: "spend"
          • directionenum
            "asc""desc"
            Default: "desc"
          • offsetinteger
            Default: 0
          • limitinteger
            Default: 50
          • as_ofstring | null

            Report cutoff. Server-set on the first read; not in the future and not before start.

            Default: null
          • snapshot_idstring

            Registered snapshot token. Requires its original as_of. Omitted from responses when unset.

        • coverageobjectrequired

          Projection freshness, independent of whether the slice is empty.

          coverage
          • as_ofstringrequired
          • projected_throughstring | nullrequired
          • completebooleanrequired
          • pending_requestsintegerrequired
          • includes_pre_admission_rejectionsboolean
            Default: false
        • totalsobjectrequired

          Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

          totals
          • countintegerrequired

            Settled requests (or terminal attempts on the attempts basis); not a success count.

          • rejected_countintegerrequired

            Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

          • errorsintegerrequired

            Non-completed requests or attempts, rejections included.

          • input_tokensintegerrequired
          • output_tokensintegerrequired
          • cached_input_tokensintegerrequired
          • reasoning_tokensintegerrequired
          • paid_nano_usdstringrequired

            Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • byok_nano_usdstringrequired

            Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • free_nano_usdstringrequired

            Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

          • unknown_usage_countintegerrequired

            Usage whose provider accounting is unknown. Nonzero makes the money provisional.

        • bucketsarray<object>required
          buckets
          • startstringrequired
          • figuresobjectrequired

            Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

            figures
            • countintegerrequired

              Settled requests (or terminal attempts on the attempts basis); not a success count.

            • rejected_countintegerrequired

              Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

            • errorsintegerrequired

              Non-completed requests or attempts, rejections included.

            • input_tokensintegerrequired
            • output_tokensintegerrequired
            • cached_input_tokensintegerrequired
            • reasoning_tokensintegerrequired
            • paid_nano_usdstringrequired

              Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • byok_nano_usdstringrequired

              Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • free_nano_usdstringrequired

              Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • unknown_usage_countintegerrequired

              Usage whose provider accounting is unknown. Nonzero makes the money provisional.

        • seriesarray<object>required
          series
          • valuestring | nullrequired
          • labelstringrequired
          • otherbooleanrequired
          • figuresobjectrequired

            Exact counters and money legs for one basis. The all-in spend is paid + BYOK + free.

            figures
            • countintegerrequired

              Settled requests (or terminal attempts on the attempts basis); not a success count.

            • rejected_countintegerrequired

              Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

            • errorsintegerrequired

              Non-completed requests or attempts, rejections included.

            • input_tokensintegerrequired
            • output_tokensintegerrequired
            • cached_input_tokensintegerrequired
            • reasoning_tokensintegerrequired
            • paid_nano_usdstringrequired

              Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • byok_nano_usdstringrequired

              Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • free_nano_usdstringrequired

              Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • unknown_usage_countintegerrequired

              Usage whose provider accounting is unknown. Nonzero makes the money provisional.

          • cellsarray<object>required
            cells
            • countintegerrequired

              Settled requests (or terminal attempts on the attempts basis); not a success count.

            • rejected_countintegerrequired

              Failed or expired requests with no provider dispatch (always 0 on the attempts basis).

            • errorsintegerrequired

              Non-completed requests or attempts, rejections included.

            • input_tokensintegerrequired
            • output_tokensintegerrequired
            • cached_input_tokensintegerrequired
            • reasoning_tokensintegerrequired
            • paid_nano_usdstringrequired

              Charged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • byok_nano_usdstringrequired

              Bring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • free_nano_usdstringrequired

              Free promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.

            • unknown_usage_countintegerrequired

              Usage whose provider accounting is unknown. Nonzero makes the money provisional.

          • kindenumrequired

            value an observed value, missing unattributed calls, other the non-selectable remainder.

            "value""missing""other"

      object

      • statusanyrequired
      • reasonanyrequired
  • 400

    Invalid Spend query, or the query lacks the frozen snapshot this route requires.

    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

    The key is not a provisioning key (inference keys are refused on every Spend route, reads included), or it is a customer-plan 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).

  • 404

    The org is not the key's own organization (always 404, never 403).

    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).

  • 409

    The snapshot (as_of + snapshot_id) expired (24 hours) or was invalidated. Refresh and replace every projection together.

    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

    Body failed schema validation ({detail:[...]}), or the report exceeds a work bound (report_too_large, series_too_large, export_too_large).

  • 503

    Reporting is unavailable, initializing, or the bounded read timed out. Not empty data; retry or narrow the range.

    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).

Request

curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/view \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-11-01T00:00:00Z",
  "end": "2026-11-08T00:00:00Z",
  "time_zone": "UTC",
  "scope": "org",
  "basis": "requests",
  "group_by": "model",
  "grain": "day",
  "filters": [],
  "tags": [],
  "sort": "spend",
  "direction": "desc",
  "offset": 0,
  "limit": 50,
  "as_of": "2026-11-19T14:02:11.418Z",
  "snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
}'

Response

{
  "report": {
    "query": {
      "start": "2026-11-01T00:00:00Z",
      "end": "2026-11-08T00:00:00Z",
      "time_zone": "UTC",
      "scope": "org",
      "basis": "requests",
      "group_by": "model",
      "grain": "day",
      "filters": [],
      "tags": [],
      "sort": "spend",
      "direction": "desc",
      "offset": 0,
      "limit": 50,
      "tag_key": null,
      "as_of": "2026-11-19T14:02:11.418Z",
      "snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
    },
    "totals": {
      "count": 18420,
      "rejected_count": 37,
      "errors": 212,
      "input_tokens": 96214000,
      "output_tokens": 8120400,
      "cached_input_tokens": 51200000,
      "reasoning_tokens": 1840000,
      "paid_nano_usd": "41382500000",
      "byok_nano_usd": "6120000000",
      "free_nano_usd": "850000000",
      "unknown_usage_count": 0
    },
    "buckets": [
      {
        "start": "2026-11-01T00:00:00Z",
        "figures": {
          "count": 2610,
          "rejected_count": 5,
          "errors": 30,
          "input_tokens": 13700000,
          "output_tokens": 1160000,
          "cached_input_tokens": 7300000,
          "reasoning_tokens": 262000,
          "paid_nano_usd": "5921000000",
          "byok_nano_usd": "870000000",
          "free_nano_usd": "120000000",
          "unknown_usage_count": 0
        }
      }
    ],
    "groups": [
      {
        "value": "gpt-6-luna",
        "label": "gpt-6-luna",
        "figures": {
          "count": 11030,
          "rejected_count": 20,
          "errors": 101,
          "input_tokens": 61200000,
          "output_tokens": 5102000,
          "cached_input_tokens": 38100000,
          "reasoning_tokens": 1840000,
          "paid_nano_usd": "29880000000",
          "byok_nano_usd": "0",
          "free_nano_usd": "0",
          "unknown_usage_count": 0
        }
      },
      {
        "value": "claude-fable-5.1",
        "label": "claude-fable-5.1",
        "figures": {
          "count": 7390,
          "rejected_count": 17,
          "errors": 111,
          "input_tokens": 35014000,
          "output_tokens": 3018400,
          "cached_input_tokens": 13100000,
          "reasoning_tokens": 0,
          "paid_nano_usd": "11502500000",
          "byok_nano_usd": "6120000000",
          "free_nano_usd": "850000000",
          "unknown_usage_count": 0
        }
      }
    ],
    "filter_labels": [],
    "group_count": 2,
    "next_offset": null,
    "coverage": {
      "as_of": "2026-11-19T14:02:11.418Z",
      "projected_through": "2026-11-08T00:00:00Z",
      "complete": true,
      "pending_requests": 0,
      "includes_pre_admission_rejections": false
    }
  },
  "series": {
    "status": "ready",
    "data": {
      "query": {
        "start": "2026-11-01T00:00:00Z",
        "end": "2026-11-08T00:00:00Z",
        "time_zone": "UTC",
        "scope": "org",
        "basis": "requests",
        "group_by": "model",
        "grain": "day",
        "filters": [],
        "tags": [],
        "sort": "spend",
        "direction": "desc",
        "offset": 0,
        "limit": 7,
        "tag_key": null,
        "as_of": "2026-11-19T14:02:11.418Z",
        "snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
      },
      "coverage": {
        "as_of": "2026-11-19T14:02:11.418Z",
        "projected_through": "2026-11-08T00:00:00Z",
        "complete": true,
        "pending_requests": 0,
        "includes_pre_admission_rejections": false
      },
      "totals": {
        "count": 18420,
        "rejected_count": 37,
        "errors": 212,
        "input_tokens": 96214000,
        "output_tokens": 8120400,
        "cached_input_tokens": 51200000,
        "reasoning_tokens": 1840000,
        "paid_nano_usd": "41382500000",
        "byok_nano_usd": "6120000000",
        "free_nano_usd": "850000000",
        "unknown_usage_count": 0
      },
      "buckets": [
        {
          "start": "2026-11-01T00:00:00Z",
          "figures": {
            "count": 2610,
            "rejected_count": 5,
            "errors": 30,
            "input_tokens": 13700000,
            "output_tokens": 1160000,
            "cached_input_tokens": 7300000,
            "reasoning_tokens": 262000,
            "paid_nano_usd": "5921000000",
            "byok_nano_usd": "870000000",
            "free_nano_usd": "120000000",
            "unknown_usage_count": 0
          }
        }
      ],
      "series": [
        {
          "value": "gpt-6-luna",
          "label": "gpt-6-luna",
          "other": false,
          "kind": "value",
          "figures": {
            "count": 11030,
            "rejected_count": 20,
            "errors": 101,
            "input_tokens": 61200000,
            "output_tokens": 5102000,
            "cached_input_tokens": 38100000,
            "reasoning_tokens": 1840000,
            "paid_nano_usd": "29880000000",
            "byok_nano_usd": "0",
            "free_nano_usd": "0",
            "unknown_usage_count": 0
          },
          "cells": [
            {
              "count": 2610,
              "rejected_count": 5,
              "errors": 30,
              "input_tokens": 13700000,
              "output_tokens": 1160000,
              "cached_input_tokens": 7300000,
              "reasoning_tokens": 262000,
              "paid_nano_usd": "5921000000",
              "byok_nano_usd": "870000000",
              "free_nano_usd": "120000000",
              "unknown_usage_count": 0
            }
          ]
        }
      ]
    }
  }
}

https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/view