> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin/cost/find-what-used-credits.md). # Review credit usage Break credit consumption down by app, agent, model, and feature. Four `GET` calls cover this, matching the UI task's balance-and-breakdown pattern. This is the API equivalent of [Review credit usage](https://docs.uptiq.ai/platform-guides/admin/cost/review-credit-usage). ## At a glance | Item | Value | | -------------------- | ----------------------------------------------- | | ⚙️ Microservice | `Identity Hub` | | 🌍 Environment | `QA` | | 🔗 Base URL | `https://api-builder-qa.uptiq.dev/identity-hub` | | ⌘ Balance endpoint | `GET /accounts/credits/balance` | | ⌘ Consumers endpoint | `GET /accounts/credits/usage/top-consumers` | | ⌘ Trends endpoint | `GET /accounts/credits/usage/trends` | | ⌘ Ledger endpoint | `GET /accounts/credits/history` | {% columns %} {% column %} #### What it does Returns the balance, top consumers, trends, and ledger entries. {% endcolumn %} {% column %} #### Success looks like Each endpoint returns `200 OK` with credit usage data. {% endcolumn %} {% endcolumns %} ## Before you start Your API key needs the **View credit usage** capability (`ViewCreditUsage`). ## Get the current balance `GET /accounts/credits/balance` — params: `startDate`, `endDate`, `projectId` (all optional). ## Code snippets ```bash curl "https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/balance" \ -H "x-platform-key: YOUR_API_KEY" \ -H "accountid: YOUR_ACCOUNT_ID" ``` ## Find what consumed credits in a window `GET /accounts/credits/usage/top-consumers` — `type` is required and must be one of `apps`, `agents`, `models` or `features` (plural; `agent` returns `400 VALIDATION_ERROR`). Narrow with `consumerId`, `projectId`, `startDate`, `endDate`, and page with `currentPage`/`pageSize`. {% tabs %} {% tab title="cURL" %} ```bash curl "https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage/top-consumers?type=agents" \ -H "x-platform-key: YOUR_API_KEY" \ -H "accountid: YOUR_ACCOUNT_ID" ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const res = await fetch( "https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage/top-consumers?type=agents", { headers: { "x-platform-key": process.env.UPTIQ_API_KEY, accountid: process.env.UPTIQ_ACCOUNT_ID, }, } ); const { data, total } = await res.json(); ``` {% endtab %} {% tab title="Python" %} ```python import os, requests res = requests.get( "https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage/top-consumers", params={"type": "agents"}, headers={ "x-platform-key": os.environ["UPTIQ_API_KEY"], "accountid": os.environ["UPTIQ_ACCOUNT_ID"], }, ) consumers = res.json()["data"] ``` {% endtab %} {% endtabs %} ## See consumption over time `GET /accounts/credits/usage/trends` — params: `groupBy` (`daily`, `weekly` or `monthly`), `startDate`, `endDate`, `projectId`. An unrecognised `groupBy` returns `400 VALIDATION_ERROR` rather than falling back to a default; omit it entirely to accept the server default. ## Reconcile the transaction-level ledger `GET /accounts/credits/history` — params: `type`, `startDate`, `endDate`, paged with `currentPage`/`pageSize`. Use this when the balance and a breakdown disagree, or you need a transaction-level record. ## Verified responses {% hint style="success" %} **Verified against QA on 22 September 2026.** Field names and nesting are exactly as returned; identifiers and figures are placeholders. {% endhint %} All four calls return the `{ message, data }` envelope; two of them add a top-level `total`. ### `GET /accounts/credits/balance` ```json { "message": "Credit balance retrieved successfully", "data": { "totalAvailableCredits": -358635, "usedCredits": 358635, "breakdown": { "monthlyAllocation": 0, "walletCredits": 0 }, "limits": [ { "duration": "Monthly", "consumedCredits": 224748, "limitCredits": 250000, "resetsAt": "2026-10-01T00:00:00.000Z" } ] } } ``` `totalAvailableCredits` **goes negative** once usage exceeds the allocation — it is a running balance, not a floor. Treat a negative value as normal, not as an error. `limits[]` is the quickest read on where an account stands against its caps, and it is the only place `resetsAt` appears. It is also visible with an account API key, unlike [the usage-limit endpoints themselves](/cookbooks/platform-admin/cost/cap-account-spending.md). ### `GET /accounts/credits/usage/top-consumers?type=agents` ```json { "message": "Top consumers retrieved successfully", "total": 43, "data": [ { "id": "856eb333-8eae-4acb-bd3a-3e17c052db80", "name": "856eb333-8eae-4acb-bd3a-3e17c052db80", "type": "Agent", "creditsUsed": 213, "costInUsd": 0.11, "lastUsed": "2026-09-18T06:15:38.197Z" }, { "id": "Unknown", "name": "Unknown", "type": "Agent", "creditsUsed": 1111, "costInUsd": 0.56, "lastUsed": "2026-09-17T11:05:31.923Z" } ] } ``` {% hint style="warning" %} **`name` is not a name.** It comes back identical to `id` — this endpoint does not resolve agent titles, so a report built straight from it lists UUIDs. Join against `GET /agent-builder/agents` if you need readable labels, remembering that call needs a session token rather than an API key. Consumption that cannot be attributed is bucketed under the literal id **`"Unknown"`**, and it can be among the largest consumers. Do not silently drop it — it is real spend. {% endhint %} `total` is the count of consumers available, not a credit figure; page with `currentPage`/`pageSize`. ### `GET /accounts/credits/usage/trends?groupBy=daily` ```json { "message": "Usage trends retrieved successfully", "data": [ { "date": "2026-07-25", "creditsUsed": 40045 }, { "date": "2026-07-30", "creditsUsed": 0 } ] } ``` Only dates with a record appear — the series is **sparse and unevenly spaced**, so a chart must fill the gaps itself rather than assuming one point per day. Zero-usage days may appear explicitly or be absent entirely; both occur. ### `GET /accounts/credits/history` ```json { "message": "Credit history retrieved successfully", "data": [ { "id": "002b2a00-d099-4698-935d-800932acf32b", "amount": 358635, "type": "Debit", "entryType": "PLATFORM_USAGE", "description": "Platform Usage", "timestamp": "2026-09-18T06:36:02.064Z", "availableCredits": -358635, "operator": "runner-runner-1" } ], "total": 2 } ``` `availableCredits` is the balance **after** that entry, which makes this the ledger to reconcile against when the balance and a breakdown disagree. `operator` identifies what caused the entry — a platform runner, or `user-` for a person. ## Developer notes | Situation | What to do | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Investigate a credit spike | Start with `top-consumers`. It identifies the agent, app, model, or feature that used credits. | | Inspect live activity | Use [Investigate an agent run](/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.md). These endpoints can lag live activity by up to one hour. | | Account for provider-key usage | Exclude usage through your own provider key. It doesn't draw on the credit balance or appear in these endpoints. | | Schedule an export | Use [Export activity data](/cookbooks/platform-admin/agents-and-evidence/export-activity-for-review.md) to create a file. Credit Usage is one of its datasets. | ## Related * [Review credit usage](https://docs.uptiq.ai/platform-guides/admin/cost/review-credit-usage) — as a screen * [Set a credit limit](/cookbooks/platform-admin/cost/cap-account-spending.md) * [Investigate an agent run](/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.uptiq.ai/cookbooks/platform-admin/cost/find-what-used-credits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.