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

Search filter values

Discovers dimension values, tag keys or tag values in the slice, ignoring only the target's own predicate. Generates no report. 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.

  • kindenum必須
    "dimension""tag_keys""tag_values"
  • dimensionenum | null
    デフォルト: null
  • tag_keystring | null
    デフォルト: null
  • searchstring
    デフォルト: ""
  • limitinteger
    デフォルト: 50
  • offsetinteger
    デフォルト: 0

レスポンス

  • 200

    OK

    レスポンス
    • 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.

    • kindenum必須
      "dimension""tag_keys""tag_values"
    • dimensionenum | null必須
    • tag_keystring | null必須
    • searchstring必須
    • optionsarray<object>必須
      options
      • valuestring | null必須
      • labelstring必須
    • next_offsetinteger | null必須
    • coverageobject必須

      Projection freshness, independent of whether the slice is empty.

      coverage
      • as_ofstring必須
      • projected_throughstring | null必須
      • completeboolean必須
      • pending_requestsinteger必須
      • includes_pre_admission_rejectionsboolean
        デフォルト: false
  • 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).

  • 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/facets \
  -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,
    "as_of": "2026-11-19T14:02:11.418Z",
    "snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
  },
  "kind": "dimension",
  "dimension": "model",
  "search": "gpt",
  "limit": 50,
  "offset": 0
}'

レスポンス

{
  "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"
  },
  "kind": "dimension",
  "dimension": "model",
  "tag_key": null,
  "search": "gpt",
  "options": [
    {
      "value": "gpt-6-luna",
      "label": "gpt-6-luna"
    }
  ],
  "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
  }
}

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