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

# Track usage

> Access organization usage data programmatically

<Note>
  These endpoints support either an organization API key in the `X-API-Key` header or a valid signed-in authorization token for a user who belongs to the organization.
</Note>

<Note>
  Generate an organization API key from your team's <a href="https://firebender.com/settings?tab=settings" target="_blank" rel="noopener">Settings → API Keys</a> page.
</Note>

## Daily usage data

Retrieve daily usage statistics for your organization.

**Endpoint:** `POST https://api.firebender.com/v2/organization/daily-usage-data`

### Example

```bash theme={null}
curl https://api.firebender.com/v2/organization/daily-usage-data \
  -H "X-API-Key: firebender_your_org_api_key_here" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"startDate": 1752144000000, "endDate": 1752230400000}' \
  | jq
```

```json theme={null}
{
  "data": [
    {
      "date": 1752192000000,
      "ideOpened": true,
      "agentPrompts": 4,
      "agentAccepts": 3,
      "agentFullAccepts": 1,
      "agentAcceptedLinesAdded": 134,
      "agentAcceptedLinesRemoved": 37,
      "inlineEdits": 0,
      "inlineEditAccepts": 0,
      "inlineAcceptedLinesAdded": 23,
      "inlineAcceptedLinesRemoved": 12,
      "autocompleteAccepts": 2,
      "autocompleteShown": 6,
      "autocompleteAcceptedCharactersAdded": 237,
      "autocompleteAcceptedCharactersRemoved": 0,
      "email": "user1@firebender.com"
    }
  ],
  "period": {
    "startDate": 1752144000000,
    "endDate": 1752230400000
  }
}
```

#### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startDate` | number | Yes | Unix timestamp in milliseconds for the start date |
| `endDate` | number | Yes | Unix timestamp in milliseconds for the end date |

#### Response Fields

| Field | Type | Description |
| - | - | - |
| `data` | array | Array of daily usage records |
| `data[].date` | number | Unix timestamp for the day |
| `data[].ideOpened` | boolean | Whether the IDE was opened that day |
| `data[].agentPrompts` | number | Number of agent prompts sent |
| `data[].agentAccepts` | number | Number of agent suggestions accepted (file accepted, individual hunk accepted) |
| `data[].agentFullAccepts` | number | Number of full agent suggestions accepted (user accepted all changes at once) |
| `data[].agentAcceptedLinesAdded` | number | Lines added through agent accepts |
| `data[].agentAcceptedLinesRemoved` | number | Lines removed through agent accepts |
| `data[].inlineEdits` | number | Number of inline edits performed |
| `data[].inlineEditAccepts` | number | Number of inline edit accepts |
| `data[].inlineAcceptedLinesAdded` | number | Lines added through inline accepts |
| `data[].inlineAcceptedLinesRemoved` | number | Lines removed through inline accepts |
| `data[].autocompleteAccepts` | number | Number of autocomplete accepts |
| `data[].autocompleteShown` | number | Number of times autocomplete was shown |
| `data[].autocompleteAcceptedCharactersAdded` | number | Characters added through autocomplete |
| `data[].autocompleteAcceptedCharactersRemoved` | number | Characters removed through autocomplete |
| `data[].email` | string | User email address |
| `period` | object | Request period information |
| `period.startDate` | number | Requested start date timestamp |
| `period.endDate` | number | Requested end date timestamp |

## Model requests

Retrieve per-request model usage for your organization, including tokens, cost, and request mode.

**Endpoint:** `POST https://api.firebender.com/v2/organization/model-requests`

### Example

```bash theme={null}
curl https://api.firebender.com/v2/organization/model-requests \
  -H "X-API-Key: firebender_your_org_api_key_here" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "startDate": 1767222900000,
    "endDate": 1767226560000
  }' \
  | jq
```

```json theme={null}
{
  "data": [
    {
      "requestId": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "timestamp": "2026-01-01T00:15:00Z",
      "email": "user1@firebender.com",
      "model": "gpt-5.4",
      "inputTokens": 120,
      "cacheReadTokens": 25,
      "outputTokens": 30,
      "cacheWriteTokens": 5,
      "totalTokens": 180,
      "costUsd": 1.2345,
      "spendType": "on-demand",
      "mode": "write"
    }
  ],
  "nextCursor": null
}
```

#### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startDate` | number | Yes | Start of the time window as a Unix timestamp in milliseconds. Data is only available on or after `2025-12-31T00:00:00Z` |
| `endDate` | number | Yes | End of the time window as a Unix timestamp in milliseconds. Must be greater than `startDate` |
| `email` | string | No | Filter results to a single user email within the organization |
| `limit` | number | No | Number of rows to return. Defaults to `100` and caps at `500` |
| `cursor` | string | No | Opaque cursor returned in a previous response to fetch the next page |

#### Response Fields

| Field | Type | Description |
| - | - | - |
| `data` | array | Array of model request records sorted oldest first |
| `data[].requestId` | string | Unique request identifier |
| `data[].timestamp` | string | Request timestamp in ISO 8601 format |
| `data[].email` | string | User email address |
| `data[].model` | string | Model identifier used for the request. See [Models](https://docs.firebender.com/get-started/models) for valid model IDs |
| `data[].inputTokens` | number | Input tokens billed for the request |
| `data[].cacheReadTokens` | number | Cache read tokens billed for the request |
| `data[].outputTokens` | number | Output tokens billed for the request |
| `data[].cacheWriteTokens` | number | Cache write tokens billed for the request |
| `data[].totalTokens` | number | Sum of input, cache read, output, and cache write tokens |
| `data[].costUsd` | number | Request cost in USD |
| `data[].spendType` | enum | Spending bucket for the request: `included` for plan-included usage, `on-demand` for metered overage usage, or `byok` for bring-your-own-key usage |
| `data[].mode` | string | Agent mode when available. Built-in modes include `write`, `plan`, `ask`, and `debug`. This can also be another user-defined string for custom agents. See [Agents/Subagents](https://docs.firebender.com/api-reference/agents) |
| `nextCursor` | string or null | Cursor for the next page, or `null` when there are no more results |

#### Notes

* Date ranges cannot exceed 90 days.
* Data is only returned for requests on or after `2025-12-31T00:00:00Z`.
* Very recent non-final requests may be withheld briefly to avoid returning unstable data.


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