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.

Authentication: Bearer API key in the Authorization header

Path parameters

  • org_idstringrequired

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

Request body

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

  • kindenumrequired
    "dimension""tag_keys""tag_values"
  • dimensionenum | null
    Default: null
  • tag_keystring | null
    Default: null
  • searchstring
    Default: ""
  • limitinteger
    Default: 50
  • offsetinteger
    Default: 0

Responses

  • 200

    OK

    Response
    • 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.

    • kindenumrequired
      "dimension""tag_keys""tag_values"
    • dimensionenum | nullrequired
    • tag_keystring | nullrequired
    • searchstringrequired
    • optionsarray<object>required
      options
      • valuestring | nullrequired
      • labelstringrequired
    • next_offsetinteger | nullrequired
    • 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
  • 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).

    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/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
}'

Response

{
  "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