---
title: "Search credit ledger entries"
method: POST
path: "/api/credit-ledger-entries/search"
tags: ["credit_ledger_entries"]
---

# Search credit ledger entries

`POST /api/credit-ledger-entries/search`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/credit-ledger-entries/search`
- Auth: HTTP bearer and API key in header `Team-SID`

Paid-call receipts - append-only: one row per billable waterfall step (failed paid steps too) with cost, tool, run/step, cell coordinates, spender. Use for: receipts of a run/cell/day/actor, "why was this cell charged twice". Requires a scope: playtable_sid/run_sid/object_sid/playtable_field_sid/created_at.gte/sid.in (else 422). Local mirror - the gtm-api ledger is authoritative billing; receipts hard-purge after 12 months. Spend totals → the metrics tool (counts here = call counts).

Contract:
- MCP tool `search_credit_ledger_entries`, registry package `mcp.playtables/credit_ledger_entries`, mount `id.billing`.
- Operation `search`, response envelope `search`.
- Flags: read only.

## Request body

- SearchCreditLedgerEntriesRequest: Request body of `search_credit_ledger_entries`.
  - `filter` object: Field filters, ANDed: {field: {eq | ne | in | nin | gte | lte | gt | lt | is_null}}; q inside it is free text. Omit for every row.
    - `sid` object: Receipt sid(s), cl_en_ prefix (prefix-validated).
      - `eq` string: Credit ledger entry (receipt) sid (cl_en_…).
      - `in` string[]
    - `playtable_sid` object: Per-table spend scope (pt_tb_…).
      - `eq` string
      - `in` string[]
    - `object_type` object: Residual inside scope: people | company.
      - `eq` 'people' | 'company'
    - `object_sid` object: cr_pp_… / cr_co_… (mixed prefixes - not prefix-pinned); cell drill-down with playtable_field_sid.
      - `eq` string
      - `in` string[]
    - `playtable_field_sid` object: Per-field spend scope (pt_fd_…).
      - `eq` string
      - `in` string[]
    - `run_sid` object: What a run cost (pt_rn_…); is_null:true = non-run spend (empty in v1 - the cell-waterfall writer always carries a run).
      - `eq` string
      - `in` string[]
      - `is_null` boolean
    - `tool_sid` object: Spend through one gtm-api tool (external sid, opaque).
      - `eq` string
      - `in` string[]
    - `created_by_actor_sid` object: "What did this person spend" - projected from created_by.actor_sid.
      - `eq` string
    - `idempotency_key` object: Support/debug: locate one exact charge.
      - `eq` string
    - `created_at` object: ISO 8601 range - day windows; combine bounds in one object. Ignored on metrics - period owns the window.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
  - `include` string[]: Relations to attach to every item; omit for the bare rows.
  - `sort` object: One column and its direction; omit for the default order.
    - `field` 'created_at' | 'cost', required: The column to order by.
    - `direction` 'asc' | 'desc': asc or desc; default desc.
  - `page_size` integer: 0..500, default 50; 0 = counts only, 1 = the first row.
  - `cursor` string, nullable: pagination.next_cursor of the previous page.

## Response `200`

`search` success envelope.

- SearchCreditLedgerEntriesResponse
  - `success` true, required
  - `operation` 'search', required
  - `items` object[], required
    - `item` object, required
      - `sid` string, required: Receipt sid (cl_en_…).
      - `team_sid` string, required: Owning team (ts_tm_…, external - gs.service.id).
      - `playtable_sid` string, nullable, required: pt_tb_… table context - see ./playtables.md; audit ref, may dangle after table delete.
      - `object_type` 'people' | 'company', nullable, required: Kind of the enriched row: people | company; null when the receipt has no cell context.
      - `object_sid` string, nullable, required: cr_pp_… / cr_co_… enriched row (polymorphic by object_type) - audit ref, may dangle.
      - `playtable_field_sid` string, nullable, required: pt_fd_… field whose waterfall spent - see ./playtable_fields.md; audit ref, may dangle.
      - `run_sid` string, nullable, required: pt_rn_… run that dispatched the step; outlives the run's 90-day purge as an opaque audit ref.
      - `step_index` integer, nullable, required: Position in the materialized waterfall; matches the cell's meta.steps[step_index].
      - `tool_sid` string, required: gtm-api tool executed (external registry sid, max 64).
      - `provider_sid` string, nullable, required: Serving provider when gtm-api resolved one; display-only - presets hide provider chains.
      - `cost` number, required: Credits this step charged (decimal(12,4), > 0 - zero-cost steps never receipt).
      - `idempotency_key` string, required: Per-step dedup axis (max 128, DB UNIQUE) shared with the gtm-api call and the tool-result callback.
      - `created_by` object, required: Spend attribution - the run initiator on whose behalf the worker spent (denormalized from the run at record time), NOT the row writer.
        - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
        - `actor_sid` string, nullable, required
        - `team_sid` string, required
        - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
        - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
        - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
        - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
        - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
        - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
      - `created_at` string, required: ISO 8601 UTC - the receipt clock and metrics period column.
    - `included` object, required
      - `field` object: 1:1 field whose waterfall spent (include[]=field): name/slug/preset for receipt display; hydrates soft-deleted fields too (audit context); absent when the field row is gone.
        - `sid` string, required
        - `name` string, required
        - `slug` string, required
        - `category` string, required
        - `type` string, required
  - `pagination` object, required
    - `next_cursor` string, nullable, required
    - `has_more` boolean, required
    - `total_count` integer, nullable, required
  - `applied_filters` object, required
  - `includes` string[], required
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.
  - `counts` object
    - `total_count` integer, required: Receipts (paid calls) matching the filter - full filter scope, not the page.
    - `groups` object, required: One axis per CreditLedgerEntryGroupableFieldsEnum value (§4.17). Values are CALL COUNTS - credit sums live in the metrics tool. PHP empty map serialises as [].
      - `playtable_sid` union, required: Flat {pt_tb_ sid: call count} - which table is spending.
        - object
        - unknown[]
          - unknown
      - `playtable_field_sid` union, required: Flat {pt_fd_ sid: call count} - call concentration by field.
        - object
        - unknown[]
          - unknown
      - `tool_sid` union, required: Flat {tool_sid: call count} - calls through each gtm-api tool.
        - object
        - unknown[]
          - unknown
      - `created_date` union, required: Flat {'YYYY-MM-DD': call count} - calls per UTC day (≤ 366 values under 12-month retention).
        - object
        - unknown[]
          - unknown

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/revisions/aa394506515d?raw)