---
title: "Model Requests"
method: POST
path: "/v2/organization/model-requests"
---

# Model Requests

`POST /v2/organization/model-requests`

Retrieve per-request model usage for your organization

## Request body

- ModelRequestsRequest
  - `startDate` integer, required — Start of the time window as a Unix timestamp in milliseconds. Data is only available on or after 2025-12-31T00:00:00Z
  - `endDate` integer, required — End of the time window as a Unix timestamp in milliseconds
  - `email` string, email — Optional email filter scoped to the organization
  - `cursor` string, nullable — Opaque cursor returned by a previous response for pagination
  - `limit` integer — Number of rows to return

## Response `200`

Model request data retrieved successfully

- ModelRequestsResponse
  - `data` ModelRequestRecord[], required — Array of model request records sorted oldest first
    - `requestId` string, uuid, required — Unique request identifier
    - `timestamp` string, date-time, required — Request timestamp in ISO 8601 format
    - `email` string, email, required — User email address
    - `model` string, required — Model identifier used for the request. See [Models](https://docs.firebender.com/get-started/models) for valid model IDs
    - `inputTokens` integer, required — Input tokens billed for the request
    - `cacheReadTokens` integer, required — Cache read tokens billed for the request
    - `outputTokens` integer, required — Output tokens billed for the request
    - `cacheWriteTokens` integer, required — Cache write tokens billed for the request
    - `totalTokens` integer, required — Sum of input, cache read, output, and cache write tokens
    - `costUsd` number, double, required — Request cost in USD
    - `spendType` 'included' | 'on-demand' | 'byok', required — Spending bucket for the request. `included` is plan-included usage, `on-demand` is metered overage usage, and `byok` is bring-your-own-key usage
    - `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 https://docs.firebender.com/api-reference/agents
  - `nextCursor` string, nullable, required — Cursor for the next page, or null when there are no more results

## Other responses

- `400` — Invalid request body, cursor, or date parameters
- `401` — Unauthorized - invalid or missing API key or authorization token
- `403` — Forbidden - authenticated user is not a member of an organization
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/firebender/apis/firebender-organization-api.md) · [All operations](https://skmtc.dev/firebender/apis/firebender-organization-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/firebender/firebender-organization-api/revisions/9c4ad5c99b7e/schema)