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

# GET /v1/agents/usage

> The AI tokens agents used on your own keys, per day, agent, pipeline and model.

Where your agents' AI tokens went — the panel's **AI agents → Usage**. The tokens are used on your own AI keys and billed by your AI provider; OMNI doesn't charge for them.

<Note>Needs the `agents:read` scope.</Note>

## Query parameters

| Field | Type | Required | Notes |
| :- | :- | :- | :- |
| `days` | integer | No | `7`, `14` or `30`; 14 by default. |

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.fireflo.au/v1/agents/usage?days=7" \
    -H "Authorization: Bearer $OMNI_API_KEY"
  ```

  ```python Python theme={null}
  import os

  import requests

  response = requests.get(
      "https://api.fireflo.au/v1/agents/usage?days=7",
      headers={"Authorization": f"Bearer {os.environ['OMNI_API_KEY']}"},
  )
  print(response.status_code, response.json())
  ```

  ```javascript Node theme={null}
  const response = await fetch("https://api.fireflo.au/v1/agents/usage?days=7", {
    headers: { Authorization: `Bearer ${process.env.OMNI_API_KEY}` },
  });
  console.log(response.status, await response.json());
  ```
</CodeGroup>

## Response

`200 OK`:

| Field | What it is |
| :- | :- |
| `totals` | Tokens (prompt and completion), AI calls and plans over the period, and an `estimated_cost_usd` — null when a model's price isn't known. |
| `days` | Each day, with tokens `by_agent` (keyed by agent id). |
| `agents` | Per agent: tokens and calls over the period, today's tokens against its `daily_limit`, plans made. |
| `pipelines` | Per pipeline agents work: tokens over the period and today, and its `daily_budget`. |
| `models` | Per provider and model: tokens, calls and estimated cost. |
| `uses` | What the tokens were for, per agent, biggest first: planning, workflow AI blocks, knowledge, hand-over summaries and the panel's AI tools. |
| `account` | Today's tokens across every agent, and the account's `daily_budget` (null for none). |

```json theme={null}
{
  "range_days": 7,
  "totals": {
    "tokens": 412870,
    "prompt_tokens": 351204,
    "completion_tokens": 61666,
    "calls": 538,
    "plans": 214,
    "estimated_cost_usd": 0.09
  },
  "days": [
    {
      "date": "2026-09-30",
      "by_agent": {
        "7": 21450,
        "12": 30118
      }
    },
    {
      "date": "2026-10-01",
      "by_agent": {
        "7": 19802,
        "12": 41260
      }
    },
    {
      "date": "2026-10-06",
      "by_agent": {
        "7": 12870,
        "12": 18450
      }
    }
  ],
  "agents": [
    {
      "agent": {
        "id": 12,
        "name": "Priya",
        "role": "support"
      },
      "model": "gpt-4o-mini",
      "tokens_today": 18450,
      "daily_limit": 100000,
      "tokens": 251322,
      "calls": 361,
      "plans": 118
    },
    {
      "agent": {
        "id": 7,
        "name": "Arjun",
        "role": "sales"
      },
      "model": "gpt-4o-mini",
      "tokens_today": 12870,
      "daily_limit": 100000,
      "tokens": 161548,
      "calls": 177,
      "plans": 96
    }
  ],
  "pipelines": [
    {
      "id": 2,
      "name": "B2B sales",
      "tokens_today": 12870,
      "daily_budget": 150000,
      "tokens": 161548
    }
  ],
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "tokens": 412870,
      "calls": 538,
      "estimated_cost_usd": 0.09
    }
  ],
  "uses": [
    {
      "agent": "Priya",
      "kind": "block",
      "label": "AI replies",
      "tokens": 162004,
      "calls": 290
    },
    {
      "agent": "Arjun",
      "kind": "planning",
      "label": "Planning (AI takes it from here)",
      "tokens": 158230,
      "calls": 170
    },
    {
      "agent": "Priya",
      "kind": "planning",
      "label": "Planning (AI takes it from here)",
      "tokens": 84318,
      "calls": 64
    }
  ],
  "account": {
    "tokens_today": 31320,
    "daily_budget": null
  }
}
```

`days` above is shortened; the answer has one entry for every day of the period.

## Errors

Every refusal is `{"error": {"code", "message", "field"}}`; `field` is there when one input is at fault.

| Status | Error code | When |
| :- | :- | :- |
| 404 | `module_off` | The account doesn't have AI agents on: they aren't in its plan, or are switched off for it. |
| 403 | `scope_missing` | The key doesn't have the `agents:read` scope. |

Any request can also be refused for its key, its account or its rate (`key_required`, `invalid_key`, `account_suspended`, `plan_excludes_api`, `address_not_allowed`, `rate_limited`); see [the overview](/api-reference/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.