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

Prepare a Spend report

Prepares an exact frozen aggregate for large ranges. Free: no usage intelligence charge. An unpinned query freezes its own snapshot; poll GET /builds/{build_id} until completed. API keys need provisioning strength and scope: org.

認証: AuthorizationヘッダーにBearer形式のAPIキー

パスパラメータ

  • org_idstring必須

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

リクエストボディ

  • queryobject必須

    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
    • startstring必須

      Inclusive start, with a UTC offset.

    • endstring必須

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

    • time_zonestring

      IANA zone for day and month buckets.

      デフォルト: "UTC"
    • scopeany
      デフォルト: "org"
    • basisany
      デフォルト: "requests"
    • group_byany
      デフォルト: "model"
    • tag_keystring | null

      Required exactly when group_by is tag.

      デフォルト: null
    • grainany
      デフォルト: "day"
    • filtersarray<object>

      At most one filter per dimension.

      デフォルト: []
      filters
      • dimensionenum必須

        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>
        デフォルト: []
      • missingboolean

        Also match calls with no value for this dimension.

        デフォルト: false
      • excludeboolean

        Invert the predicate. Must be a JSON boolean.

        デフォルト: false
    • tagsarray<object>

      At most one predicate per tag key.

      デフォルト: []
      tags
      • keystring必須
      • valuesarray<string>
        デフォルト: []
      • missingboolean

        Also match calls without this tag key.

        デフォルト: false
      • excludeboolean
        デフォルト: false
    • sortany
      デフォルト: "spend"
    • directionenum
      "asc""desc"
      デフォルト: "desc"
    • offsetinteger
      デフォルト: 0
    • limitinteger
      デフォルト: 50
    • as_ofstring | null

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

      デフォルト: null
    • snapshot_idstring

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

レスポンス

  • 200

    OK

    レスポンス
    • idstring必須
    • statusenum必須

      Currently returned: running, completed, failed or expired.

      "queued""running""completed""failed""cancelled""expired"
    • queryobject必須

      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
      • startstring必須

        Inclusive start, with a UTC offset.

      • endstring必須

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

      • time_zonestring

        IANA zone for day and month buckets.

        デフォルト: "UTC"
      • scopeany
        デフォルト: "org"
      • basisany
        デフォルト: "requests"
      • group_byany
        デフォルト: "model"
      • tag_keystring | null

        Required exactly when group_by is tag.

        デフォルト: null
      • grainany
        デフォルト: "day"
      • filtersarray<object>

        At most one filter per dimension.

        デフォルト: []
        filters
        • dimensionenum必須

          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>
          デフォルト: []
        • missingboolean

          Also match calls with no value for this dimension.

          デフォルト: false
        • excludeboolean

          Invert the predicate. Must be a JSON boolean.

          デフォルト: false
      • tagsarray<object>

        At most one predicate per tag key.

        デフォルト: []
        tags
        • keystring必須
        • valuesarray<string>
          デフォルト: []
        • missingboolean

          Also match calls without this tag key.

          デフォルト: false
        • excludeboolean
          デフォルト: false
      • sortany
        デフォルト: "spend"
      • directionenum
        "asc""desc"
        デフォルト: "desc"
      • offsetinteger
        デフォルト: 0
      • limitinteger
        デフォルト: 50
      • as_ofstring | null

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

        デフォルト: null
      • snapshot_idstring

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

    • created_atstring必須
    • updated_atstring必須
    • expires_atstring必須
    • progressobject必須

      Committed checkpoint counters, not a percent complete.

      progress
      • processed_factsinteger必須
      • processed_sourcesinteger必須
      • phaseenum必須
        "coverage""aggregate""publish"
    • error_codestring | null必須
  • 400

    Invalid Spend query (bad filter value, a future as_of, a personal scope: self from a key, or a missing snapshot where one is required).

    レスポンス
    • errorstring必須

      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.

    レスポンス
    • errorstring必須

      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.

    レスポンス
    • errorstring必須

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

    レスポンス
    • errorstring必須

      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.

    レスポンス
    • errorstring必須

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

  • 429

    Report preparation is at capacity. Carries Retry-After: 1.

    レスポンス
    • errorstring必須

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

  • 503

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

    レスポンス
    • errorstring必須

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

リクエスト

curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/builds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}'

レスポンス

{
  "id": "8d2f1c6a-3e4b-4a7d-b9e0-5c1f2a7d8e30",
  "status": "running",
  "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"
  },
  "created_at": "2026-11-19T14:02:11.420Z",
  "updated_at": "2026-11-19T14:02:12.031Z",
  "expires_at": "2026-11-20T14:02:11.420Z",
  "progress": {
    "processed_facts": 0,
    "processed_sources": 0,
    "phase": "coverage"
  },
  "error_code": null
}

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