> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Track API usage, credit consumption, and per-agent AI spend.

## Overview

Two usage streams roll up onto the dashboard's **Usage** tab and into the `/v1/usage` API:

* **Per-call usage** — every successful and failed call to `/v1/data/*`, `/v1/connections/*`, `/v1/db/*` writes a row to `usage_logs` with the provider id, the endpoint, latency, status, and cost in data credits.
* **Per-session AI usage** — every deployed-agent session writes one or more `agent_compute_usage` rows with token counts, cache hits, runtime ms, and cost in AI credits.

## Dashboard

Open **Usage** in the dashboard sidebar. The page shows:

* **Daily credit consumption** for the data and AI wallets, side by side.
* **Per-agent breakdown** — which deployed agents are burning the most AI credits, with a click-through to the agent's session list.
* **Top providers** — which data APIs and connections are taking the most data credits.
* **Recent calls** — the live tail of `usage_logs` with status, latency, and the exact MCP tool name if the call came from an agent.

You can also drill into any single deployed agent from **Agents → \<agent>** to see only that agent's usage, both data and AI.

## Usage API

Pull the same data programmatically:

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Parameters

| Parameter    | Type    | Description                                                          |
| ------------ | ------- | -------------------------------------------------------------------- |
| `limit`      | integer | Max rows to return (default 50).                                     |
| `offset`     | integer | Pagination offset.                                                   |
| `providerId` | string  | Filter to one data source or connection (e.g. `linkedin`, `stripe`). |
| `status`     | string  | `success` or `error`.                                                |
| `from`       | string  | ISO 8601 start.                                                      |
| `to`         | string  | ISO 8601 end.                                                        |

### Example

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/usage?from=2026-04-01&to=2026-04-30&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "…",
      "providerId": "linkedin",
      "endpoint": "/get-company-details",
      "costCents": 1,
      "status": "success",
      "createdAt": "2026-04-15T10:30:00Z"
    }
  ]
}
```

When a row originates from a deployed agent, the metadata object includes `tool_name` (the exact MCP tool name the agent called) and `deployed_agent_id` so you can correlate API spend back to a specific agent.

## Agent compute usage

For AI credits specifically, each session row carries the breakdown:

| Field                                      | Meaning                                                                 |
| ------------------------------------------ | ----------------------------------------------------------------------- |
| `input_tokens`                             | Tokens sent to the model in this turn or aggregated across the session. |
| `output_tokens`                            | Tokens the model generated.                                             |
| `cache_read_tokens` / `cache_write_tokens` | Prompt-caching activity.                                                |
| `runtime_ms`                               | Wall-clock time the managed runtime took.                               |
| `cost_cents`                               | Total deducted from the AI wallet for this row.                         |

You can inspect this from inside the Builder via `get_agent_session_usage` (per session) or from the dashboard's agent detail page (per agent, rolled up over time).

## Best practices

<AccordionGroup>
  <Accordion title="Cache aggressively">
    Repeat lookups against the same identifier within a short window are good candidates for application-level caching. The data APIs include latency hints but they don't dedupe across requests.
  </Accordion>

  <Accordion title="Right-size endpoints">
    Light-touch endpoints (e.g. profile basics) cost less than deep enrichment. Pick the smallest endpoint that gets you the data you actually use.
  </Accordion>

  <Accordion title="Prune unused agent tools">
    Every tool you expose to an agent is loaded into its context window and counts against input tokens on every turn. Strip tools the agent never uses to lower AI credit burn.
  </Accordion>

  <Accordion title="Monitor regularly">
    The Usage tab is the cheapest way to spot regressions. A sudden spike in one provider's calls usually points at a logic bug, not a feature win.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Credits" icon="coins" href="/billing/credits">
    Data wallet vs. AI wallet, auto-reload, balance checks.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/concepts/rate-limits">
    Per-plan RPM and backoff.
  </Card>

  <Card title="API keys" icon="key" href="/authentication/api-keys">
    Manage workspace API keys.
  </Card>
</CardGroup>