> Source: [/docs/api/fee-payer-usage](https://tempo.xyz/developers/docs/api/fee-payer-usage.md) > Section: [API reference](https://tempo.xyz/developers/docs/api.md). Tempo API reference: authentication, conventions, endpoints grouped by product, Console management endpoints, JSON-RPC, and the indexer. An API key authenticates API requests; an account signing key authorizes transactions. > [Documentation index](https://tempo.xyz/developers/llms.txt) · [Docs skill](https://tempo.xyz/developers/SKILL.md) > Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation. > If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.xyz/developers/llms.txt) and Markdown pages directly. # Fee payer ## Get Fee Payer usage `GET /v1/orgs/{orgId}/usage/fee-payer` Hourly or daily sponsorship volume, actual USD fees, and individual usage records. ### Path parameters - `orgId` `string` _(required)_: Organization id. ### Query parameters - `cursor` `string`: Opaque keyset cursor from a previous response (`nextCursor`); pass it back verbatim to fetch the next page. Omit for the first (head) page. - `environment` `string`: API-key environment. - `from` `string `: Inclusive creation time; defaults to 30 days before the end. - `interval` `string`: UTC chart bucket size. - `limit` `integer`: How many items to return per page (5–50, default 10). Use `nextCursor` to fetch more. - `projectId` `string`: Project owning the sponsorships. - `to` `string `: Exclusive creation time; defaults to now. ### Responses #### `200`: Fee Payer usage and history. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. Body (`application/json`): - `data` `object[]` _(required)_: Usage history, newest first. - `createdAt` `string ` _(required)_: ISO 8601 timestamp. - `id` `string` _(required)_: Sponsorship id. - `sponsoredUsd` `string` _(required)_: Actual USD fee; null while pending or if its currency is unknown. - `status` `string` _(required)_: Sponsorship status. - `transactionHash` `string` _(required)_: Transaction hash, when available. - `from` `string ` _(required)_: ISO 8601 timestamp. - `nextCursor` `string` _(required)_: Pass this back as the `cursor` query parameter to fetch the next page. `null` once you have reached the end of the list. - `series` `object[]` _(required)_: Volume and actual fees by UTC bucket on the first page; empty on cursor pages. Empty buckets are omitted. - `count` `integer` _(required)_: Sponsorship requests in the bucket, including pending and failed requests. - `date` `string | string ` _(required)_: UTC bucket start: date for daily buckets, timestamp for hourly buckets. - `sponsoredUsd` `string` _(required)_: Actual sponsored fees in USD, excluding pending fee caps. - `to` `string ` _(required)_: ISO 8601 timestamp. #### `400`: Invalid request. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `401`: Missing or invalid API key. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `403`: Forbidden. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `404`: Not found. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `429`: Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. - `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `500`: Internal server error. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `502`: Upstream data failure. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `504`: Request timed out. The request did not complete within the 60-second deadline; retry it. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. ### Example request ```bash curl 'https://api.tempo.xyz/v1/orgs/org_acme/usage/fee-payer?cursor=WzIzNDU2Nzg5LDBd&environment=sandbox&from=2026-01-01T00:00:00.000Z&interval=hour&limit=10&projectId=prj_checkout&to=2026-02-01T00:00:00.000Z' ``` ```ts fetch('https://api.tempo.xyz/v1/orgs/org_acme/usage/fee-payer?cursor=WzIzNDU2Nzg5LDBd&environment=sandbox&from=2026-01-01T00:00:00.000Z&interval=hour&limit=10&projectId=prj_checkout&to=2026-02-01T00:00:00.000Z') ``` ## Get sponsorship usage `GET /v1/orgs/{orgId}/usage/sponsorships` ### Path parameters - `orgId` `string` _(required)_: The organization id (`org_…`). ### Query parameters - `environment` `string`: Only include sponsorships requested under this key environment. - `from` `string `: Window start (ISO 8601), inclusive. Defaults to 30 days before `to`. - `interval` `string`: Bucket width, aligned to UTC calendar boundaries. - `projectId` `string`: Only include sponsorships attributed to this project (`prj_…`). - `to` `string `: Window end (ISO 8601), exclusive. Defaults to now. ### Responses #### `200`: The organization's sponsorship usage series. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. Body (`application/json`): - `data` `object[]` _(required)_: Time-ordered usage buckets; buckets with no sponsorships are omitted. - `count` `number` _(required)_: Sponsored transactions recorded in the bucket, any status. - `failed` `number` _(required)_: Sponsored transactions in the bucket whose status is `failed`. - `feeTotal` `object` _(required)_: Committed fees for the bucket. - `amount` `string` _(required)_: Committed fees as a decimal string: finalized fees plus in-flight fee caps; failed rows contribute zero. - `currency` `string` _(required)_: Currency of the fee figure. - `timestamp` `string ` _(required)_: Bucket start (ISO 8601), aligned to UTC calendar boundaries. #### `400`: Malformed API key, invalid path, or invalid query. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `401`: Missing or invalid API key. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `403`: Forbidden. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `404`: No accessible organization was found for this id. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `429`: Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. - `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `500`: Internal server error. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `502`: Upstream data failure. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `504`: Request timed out. The request did not complete within the 60-second deadline; retry it. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. ### Example request ```bash curl 'https://api.tempo.xyz/v1/orgs/org_1a2b3c4d5e6f7g8h9j0k1m2n/usage/sponsorships?environment=production&from=2026-01-01T00:00:00Z&interval=day&projectId=prj_1a2b3c4d5e6f7g8h9j0k1m2n&to=2026-01-31T00:00:00Z' ``` ```ts fetch('https://api.tempo.xyz/v1/orgs/org_1a2b3c4d5e6f7g8h9j0k1m2n/usage/sponsorships?environment=production&from=2026-01-01T00:00:00Z&interval=day&projectId=prj_1a2b3c4d5e6f7g8h9j0k1m2n&to=2026-01-31T00:00:00Z') ```