--- title: "Credit spend by day" method: POST path: "/api/credit-transactions/metrics" tags: ["credit_transactions"] --- # Credit spend by day `POST /api/credit-transactions/metrics` ## Request - Base URL: `https://beta.getsales.io/id/v1` - URL: `https://beta.getsales.io/id/v1/api/credit-transactions/metrics` - Auth: HTTP bearer and API key in header `Team-SID` The workspace's credit spend over a REQUIRED period: spent (the confirmed debits), charged (their count, the units of work), granted and expired, counted by type, status, operation, day, product, feature, thing, container, person and starter. group_by created_date is the burn per day; filter.product with group_by container_sid reads a product by its tables or sender profiles, object_sid a table by its columns, actor_sid the people. The balance now is get_credit_lots_metrics. Contract: - MCP tool `get_credit_transactions_metrics`, registry package `mcp.id/credit_transactions`, mount `id.billing`. - Operation `metrics`, response envelope `metrics`. - Flags: read only. ## Request body - GetCreditTransactionsMetricsRequest: Request body of `get_credit_transactions_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. - `type` 'allocation' | 'debit' | 'refund' | 'expiry': One movement type. - `status` 'pending' | 'confirmed' | 'released' | 'expired': One status. - `operation` string: One wallet operation label (gtm_tool_call, llm.generate, ai_sdr_turn, creator_turn...). - `product` 'playtables' | 'ai_sdr' | 'creator' | 'voice': One product: playtables (the columns, the searches, the work emails), ai_sdr (the agent), creator (its chats), voice (dictation and a voice message). - `feature` string: One kind of work in the product's own word: use_ai, ai_search, enrichment, email_find, dialog_reply, draft, knowledge, chat, dictation... - `object_sid` string: One thing: a column (pt_fd_), a data source (ds_sc_), a conversation (ub_cv_), a Creator chat (ct_ss_). - `container_sid` string: One holder of things: a playtable (pt_tb_), a sender profile (ub_sp_). - `actor_sid` string: One person (us_mb_) the credits count for: who ran it, who asked Creator, who set up the column that runs on new rows. - `started_by` 'user' | 'creator' | 'api' | 'automation' | 'agent' | 'lead': Who set it going: user, creator (for a person), api, automation (a column on new rows), agent (the AI SDR by itself), lead (a voice message). - `period` object, required: Required. Half-open [from, to) window on created_at, the UTC day a movement belongs to (a hold is born at reserve and captured inside its 15 minutes). - `from` string, required: ISO 8601 UTC window start (inclusive). - `to` string, required: ISO 8601 UTC window end (exclusive); must be >= from. - `group_by` 'type' | 'status' | 'operation' | 'created_date' | 'product' | 'feature' | 'object_sid' | 'container_sid' | 'actor_sid' | 'started_by': One axis: created_date (the burn per UTC day), product, container_sid (tables, sender profiles), object_sid (columns, chats), actor_sid (people), feature, started_by, operation, type or status; adds groups[] with counts and metrics. Cap 500. ## Response `200` `metrics` success envelope. - GetCreditTransactionsMetricsResponse - `success` true, required - `operation` 'metrics', required - `metrics` object, required - `filter` union: Echo of the kind and the pinned axis values the numbers are for. - object - unknown[] - unknown - `period` object, required - `from` string, required - `to` string, required - `aggregated` object, required - `counts` object, required - `total_count` integer, required: Movements in [from, to): every type and status. - `groups` object, required: One axis per CreditTransactionGroupableFieldsEnum value: row counts, never credits. - `type` union, required: Flat {type: rows}: allocation | debit | refund | expiry. - object - unknown[] - … - `status` union, required: Flat {status: rows}: pending (a hold in flight) | confirmed | released (a hold voided) | expired (a hold that lapsed). - object - unknown[] - … - `operation` union, required: Flat {operation: rows}: what spent, gtm_tool_call (a column), find_people_search (a Find people walk), creator_turn (the Creator); "" for rows that carry none. - object - unknown[] - … - `created_date` union, required: Flat {'YYYY-MM-DD': rows}: movements per UTC day of created_at. - object - unknown[] - … - `product` union, required: Flat {product: rows}: playtables | ai_sdr | creator | voice; "" for a movement that says nothing (an allocation, an expiry, a debit before 2026-10-23). - object - unknown[] - … - `feature` union, required: Flat {feature: rows}: the kind of work in the product's own word. - object - unknown[] - … - `object_sid` union, required: Flat {sid: rows}: the thing the movement belongs to. - object - unknown[] - … - `container_sid` union, required: Flat {sid: rows}: the playtable or the sender profile that holds the thing. - object - unknown[] - … - `actor_sid` union, required: Flat {sid: rows}: the person the credits count for. - object - unknown[] - … - `started_by` union, required: Flat {starter: rows}: user | creator | api | automation | agent | lead. - object - unknown[] - … - `metrics` object, required - `spent` number, required: Credits the confirmed debits took in [from, to), two decimals (five 0.1 verifications are 0.5): a pending hold is reserved, not spent; a released or expired hold never left the wallet. - `granted` number, required: Credits the confirmed allocations and refunds brought in [from, to). - `expired` number, required: Credits that lapsed unspent in [from, to): a period's lot dies with the period. - `charged` integer, required: How many confirmed debits there were: the units of work paid for (a cell, a page, a found address, a turn is one each); a count of all debit rows would read the voided holds too. - `groups` object[]: Present only when group_by was set: one entry per axis value in the window, ascending by key. - `key` string, nullable, required: Value of the group_by axis: a 'YYYY-MM-DD' day, a type, a status, an operation, a product, a feature, a sid or a starter; null = rows without a value on the axis (an allocation has no operation, no product). - `counts` object, required - `total_count` integer, required: Movements in [from, to): every type and status. - `groups` object, required: One axis per CreditTransactionGroupableFieldsEnum value: row counts, never credits. - `type` union, required: Flat {type: rows}: allocation | debit | refund | expiry. - object - unknown[] - … - `status` union, required: Flat {status: rows}: pending (a hold in flight) | confirmed | released (a hold voided) | expired (a hold that lapsed). - object - unknown[] - … - `operation` union, required: Flat {operation: rows}: what spent, gtm_tool_call (a column), find_people_search (a Find people walk), creator_turn (the Creator); "" for rows that carry none. - object - unknown[] - … - `created_date` union, required: Flat {'YYYY-MM-DD': rows}: movements per UTC day of created_at. - object - unknown[] - … - `product` union, required: Flat {product: rows}: playtables | ai_sdr | creator | voice; "" for a movement that says nothing (an allocation, an expiry, a debit before 2026-10-23). - object - unknown[] - … - `feature` union, required: Flat {feature: rows}: the kind of work in the product's own word. - object - unknown[] - … - `object_sid` union, required: Flat {sid: rows}: the thing the movement belongs to. - object - unknown[] - … - `container_sid` union, required: Flat {sid: rows}: the playtable or the sender profile that holds the thing. - object - unknown[] - … - `actor_sid` union, required: Flat {sid: rows}: the person the credits count for. - object - unknown[] - … - `started_by` union, required: Flat {starter: rows}: user | creator | api | automation | agent | lead. - object - unknown[] - … - `metrics` object, required - `spent` number, required: Credits the confirmed debits took in [from, to), two decimals (five 0.1 verifications are 0.5): a pending hold is reserved, not spent; a released or expired hold never left the wallet. - `granted` number, required: Credits the confirmed allocations and refunds brought in [from, to). - `expired` number, required: Credits that lapsed unspent in [from, to): a period's lot dies with the period. - `charged` integer, required: How many confirmed debits there were: the units of work paid for (a cell, a page, a found address, a turn is one each); a count of all debit rows would read the voided holds too. - `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)