---
title: "Credit wallet balance"
method: POST
path: "/api/credit-lots/metrics"
tags: ["credit_lots"]
---

# Credit wallet balance

`POST /api/credit-lots/metrics`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/credit-lots/metrics`
- Auth: HTTP bearer and API key in header `Team-SID`

The workspace's credit wallet, open to every member: available (spendable now), held (reserved by running work), granted and remaining over the active lots, next_expiry_at with next_expiry_amount (the dated lots alone; the plan's credits live with the plan), next_grant_at (the next monthly grant); counts.total_count is the active lots. One US dollar is 25 credits. A run's cost is its estimate (/mcp/playtables/columns); what was spent is the credit ledger (/mcp/playtables/sources).

Contract:
- MCP tool `get_credit_lots_metrics`, registry package `mcp.id/credit_lots`, mount `id.billing`.
- Operation `metrics`, response envelope `metrics`.
- Flags: read only.

## Request body

- GetCreditLotsMetricsRequest: Request body of `get_credit_lots_metrics`.
  - `filter` object: Scopes the rows the metrics are computed over: the search filter operators. Omit for all rows.
    - `kind` 'platform': The wallet axis; platform is the one kind, the default.

## Response `200`

`metrics` success envelope.

- GetCreditLotsMetricsResponse
  - `success` true, required
  - `operation` 'metrics', required
  - `metrics` object, required
    - `filter` object
    - `period` object
      - `from` string, required
      - `to` string, required
    - `aggregated` object
      - `counts` object
      - `metrics` object
        - `kind` 'platform', required: The wallet axis the numbers are for.
        - `available` number, required: Credits the workspace can spend now: the active lots minus the holds of running work. Two decimals (0.01 is the smallest amount).
        - `held` number, required: Credits reserved by work in flight (a run, a play), released or captured when it ends.
        - `granted` number, required: Credits issued over the active lots.
        - `remaining` number, required: What is left of the active lots before the holds.
        - `next_expiry_at` string, nullable, required: ISO 8601 UTC when the soonest DATED lot lapses (the trial's grant, credits bought with no plan); null = none. The plan's lots carry no date: they live with the plan and burn when the workspace leaves it.
        - `next_expiry_amount` number, required: How many credits lapse then; 0 when no lot is active.
        - `next_grant_at` string, nullable, required: ISO 8601 UTC when the next monthly grant lands through the workspace's share (the battery's refill); null with no recurring credits.
    - `metrics` object
      - `kind` 'platform', required: The wallet axis the numbers are for.
      - `available` number, required: Credits the workspace can spend now: the active lots minus the holds of running work. Two decimals (0.01 is the smallest amount).
      - `held` number, required: Credits reserved by work in flight (a run, a play), released or captured when it ends.
      - `granted` number, required: Credits issued over the active lots.
      - `remaining` number, required: What is left of the active lots before the holds.
      - `next_expiry_at` string, nullable, required: ISO 8601 UTC when the soonest DATED lot lapses (the trial's grant, credits bought with no plan); null = none. The plan's lots carry no date: they live with the plan and burn when the workspace leaves it.
      - `next_expiry_amount` number, required: How many credits lapse then; 0 when no lot is active.
      - `next_grant_at` string, nullable, required: ISO 8601 UTC when the next monthly grant lands through the workspace's share (the battery's refill); null with no recurring credits.
  - `applied_filters` object
  - `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.

## 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-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)