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

> ## Agent Instructions
> Agents: start with https://docs.pre.dev/agents.md, which has complete recipes, plan access, polling rules, errors and limits.
> Authenticate with the workspace API key (pdk_…) from Integrations → Built-in, sent as Authorization: Bearer <key>.
> REST API: https://api.pre.dev (OpenAPI: https://docs.pre.dev/api-reference/openapi.json). AI Gateway: https://api.pre.dev/v1, OpenAI-compatible (OpenAPI: https://docs.pre.dev/api-reference/ai-gateway.openapi.json).
> pre.dev MCP server: https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp.

# Usage

> Per-call headers, GET /v1/usage for totals by model, and GET /v1/generation for one call.

## Per-call headers

| Header | Meaning |
| - | - |
| `x-predev-request-id` | `pdr_…`, on every inference call; quote it when contacting support |
| `x-predev-credits-charged` | Credits charged for this call, on completed non-streaming calls |
| `x-predev-credits-remaining` | Workspace balance after the call; omitted when the workspace has no credit limit |

Send `x-predev-project-id: <projectId>` on a request to attribute it to one of the workspace's projects. Ids of projects the workspace does not own are ignored.

## Usage totals

`GET /v1/usage` returns totals for the last `days` days (1 to 90, default 30), broken down by model and path. The read is not charged.

```bash theme={null}
curl --fail-with-body "https://api.pre.dev/v1/usage?days=30" \
  -H "Authorization: Bearer $PREDEV_API_KEY"
```

```json theme={null}
{
  "workspace": "ws_3f9a1c07b2e4d5a8",
  "project": null,
  "credits_remaining": 412.5,
  "tier": "SoloPro",
  "since": "2026-08-28T00:00:00.000Z",
  "totals": { "requests": 1840, "credits": 87.5 },
  "by_model": [
    {
      "model": "deepseek/deepseek-v4.1-flash",
      "path": "/chat/completions",
      "requests": 1702,
      "credits": 41.2,
      "prompt_tokens": 9120000,
      "completion_tokens": 1410000,
      "errors": 3
    },
    {
      "model": "anthropic/claude-sonnet-5",
      "path": "/messages",
      "requests": 138,
      "credits": 46.3,
      "prompt_tokens": 610000,
      "completion_tokens": 92000,
      "errors": 0
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `workspace` | An opaque, stable id (`ws_` and 16 hex characters) for the workspace the key belongs to |
| `project` | The project named by `x-predev-project-id`, or `null` |
| `credits_remaining` | Current balance; `null` when the workspace has no credit limit |
| `tier` | Plan tier |
| `since` | Start of the window |
| `totals.requests`, `totals.credits` | Window totals |
| `by_model[].model`, `path` | One row per model and endpoint |
| `by_model[].requests`, `credits` | Volume and credits for that row |
| `by_model[].prompt_tokens`, `completion_tokens` | Token totals |
| `by_model[].errors` | Requests that returned an error |

## One generation

[`GET /v1/generation?id=<id>`](/ai-gateway/api/generation) returns the record of one call, using the `pdg-…` id from the response body, or from a stream chunk once the stream ends. Only this workspace's generations are visible. Stats can take a few seconds to appear after a call; a `404` with code `not_ready` means retry shortly.

```bash theme={null}
curl --fail-with-body "https://api.pre.dev/v1/generation?id=pdg-7c1e4b52-9a3d-4f8e-b0c6-2d5a8e913f47" \
  -H "Authorization: Bearer $PREDEV_API_KEY"
```

The body's `data` object reports the model, timing (`latency`, `generation_time`), `finish_reason`, whether the call streamed or was cancelled, token counts including reasoning and cached tokens, counts of images and other attachments, and `credits`: the credits charged for the call.


## OpenAPI

````yaml api-reference/ai-gateway.openapi.json GET /v1/usage
openapi: 3.1.0
info:
  title: pre.dev AI Gateway API
  version: 1.0.0
  description: >-
    One OpenAI-compatible API for hundreds of models from every major lab, paid
    for in pre.dev credits.


    - **Base URL:** `https://api.pre.dev/v1` for the OpenAI SDKs. The Anthropic
    SDKs take `https://api.pre.dev` and add `/v1/messages` themselves.

    - **Auth:** the workspace API key (`pdk_…`) from Integrations → Built-in in
    the pre.dev dashboard, as `Authorization: Bearer <key>` or `x-api-key`. Keep
    it on a server: it spends the workspace's credits.

    - **Models:** send ids exactly as `GET /v1/models` lists them, such as
    `anthropic/claude-sonnet-5`.

    - **Public directory:** `GET /v1/models/public` lists every model with no
    key and no prices.

    - **Charges:** each call is charged in credits from its metered cost.
    Non-streaming responses report the charge in `x-predev-credits-charged`;
    `GET /v1/generation` reports it for any call. A request is refused with
    `402` before it runs when the balance cannot cover it. Catalog, usage,
    generation and file reads are free.

    - **Limits:** 600 requests per minute per workspace, 30 on the free trial. A
    free workspace can spend 5 credits on AI calls in total, then gets `402
    subscription_required`. Reads other than `GET /v1/files` do not count toward
    the per-minute limit.

    - **Errors:** errors raised by pre.dev use the OpenAI error shape with a
    `predev` object (`GatewayError`). Errors from the model keep their HTTP
    status and message (`ModelError`). Every inference response carries
    `x-predev-request-id`.

    - **Streaming:** `stream: true` returns server-sent events in the native
    format of each endpoint. Lines that start with `:` are keep-alives.


    Example values are illustrative.
  contact:
    name: pre.dev Support
    url: https://pre.dev
    email: support@pre.dev
  license:
    name: Proprietary
    url: https://pre.dev/terms
servers:
  - url: https://api.pre.dev
    description: Production
security:
  - apiKeyAuth: []
  - xApiKey: []
tags:
  - name: Chat
    description: Chat completions, text completions, Responses and Messages.
  - name: Embeddings
    description: Embeddings and rerank.
  - name: Images and video
    description: Image generation and asynchronous video jobs.
  - name: Audio
    description: Speech, music and transcription.
  - name: Files
    description: Documents stored for later chat requests.
  - name: Models
    description: The model catalog, with credit prices.
  - name: Usage
    description: Usage totals and per-call stats.
paths:
  /v1/usage:
    get:
      tags:
        - Usage
      summary: Get usage
      description: >-
        Totals for the workspace over the last `days` days, broken down by model
        and endpoint. Free.
      operationId: getUsage
      parameters:
        - name: days
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 30
          description: Window length. Values outside 1 to 90 are clamped.
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Usage totals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
              example:
                workspace: ws_3f9a1c07b2e4d5a8
                project: null
                credits_remaining: 412.5
                tier: EnterprisePremium
                since: '2026-08-28T12:00:00.000Z'
                totals:
                  requests: 1840
                  credits: 87.5
                by_model:
                  - model: anthropic/claude-sonnet-5
                    path: /messages
                    requests: 138
                    credits: 46.3
                    prompt_tokens: 610000
                    completion_tokens: 92000
                    errors: 0
                  - model: deepseek/deepseek-v4.1-flash
                    path: /chat/completions
                    requests: 1702
                    credits: 41.2
                    prompt_tokens: 9120000
                    completion_tokens: 1410000
                    errors: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/AuthFailures'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    ProjectId:
      name: x-predev-project-id
      in: header
      required: false
      schema:
        type: string
      description: >-
        Attribute this call to one of the workspace's projects. An id the
        workspace does not own is ignored.
  schemas:
    Usage:
      type: object
      required:
        - workspace
        - project
        - credits_remaining
        - tier
        - since
        - totals
        - by_model
      properties:
        workspace:
          type: string
          pattern: ^ws_[0-9a-f]{16}$
          description: >-
            An opaque, stable id for the workspace the key belongs to (a
            personal account or a team).
        project:
          type:
            - string
            - 'null'
          description: >-
            The project from `x-predev-project-id` when the workspace owns it,
            else `null`. The totals always cover the whole workspace.
        credits_remaining:
          type:
            - number
            - 'null'
          description: Current balance. `null` on plans without a credit limit.
        tier:
          type: string
          description: Plan tier, for example `Trial` or `SoloPro`.
        since:
          type: string
          format: date-time
          description: Start of the window.
        totals:
          type: object
          required:
            - requests
            - credits
          properties:
            requests:
              type: integer
            credits:
              type: number
          additionalProperties: true
        by_model:
          type: array
          description: One row per model and endpoint, most credits first.
          items:
            type: object
            required:
              - model
              - path
              - requests
              - credits
            properties:
              model:
                type:
                  - string
                  - 'null'
                description: The model that served the calls; `null` when none answered.
              path:
                type: string
                examples:
                  - /chat/completions
              requests:
                type: integer
              credits:
                type: number
              prompt_tokens:
                type: integer
              completion_tokens:
                type: integer
              errors:
                type: integer
                description: Calls that returned HTTP 400 or higher.
            additionalProperties: true
      additionalProperties: true
    GatewayError:
      type: object
      description: >-
        An error raised by pre.dev, in the OpenAI error shape with an extra
        `predev` object (absent on `catalog_unavailable` from the catalog
        listings). Branch on `error.code`.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - param
          properties:
            message:
              type: string
              description: What went wrong and what to do next.
            type:
              type: string
              enum:
                - authentication_error
                - insufficient_credits
                - subscription_required
                - invalid_request_error
                - not_found_error
                - rate_limit_error
                - server_error
              description: >-
                Error class. The OpenAI and Anthropic SDKs map the HTTP status
                to their own exception types.
            code:
              type: string
              enum:
                - missing_api_key
                - invalid_api_key
                - too_many_auth_failures
                - insufficient_credits
                - subscription_required
                - rate_limit_exceeded
                - balance_unavailable
                - invalid_request
                - missing_id
                - not_found
                - not_ready
                - upstream_unavailable
                - catalog_unavailable
                - internal_error
              description: >-
                | Code | HTTP | Meaning |

                | --- | --- | --- |

                | `missing_api_key` | 401 | No `Authorization: Bearer` or
                `x-api-key` header. |

                | `invalid_api_key` | 401 | The key is unknown, or was rotated
                more than 15 minutes ago. |

                | `too_many_auth_failures` | 429 | More than 30 failed key
                attempts from this IP address in a minute. |

                | `insufficient_credits` | 402 | The balance is zero or below
                the estimate for this request. Nothing ran. |

                | `subscription_required` | 402 | A free workspace used its 5
                credits of AI calls. |

                | `rate_limit_exceeded` | 429 | Over the per-minute request
                limit for the workspace. |

                | `balance_unavailable` | 503 | The balance could not be read.
                Nothing ran. |

                | `invalid_request` | 400 | `/v1/audio/speech` is missing
                `model` or `input`, or the model does not produce audio. |

                | `missing_id` | 400 | `/v1/generation` was called without `id`.
                |

                | `not_found` | 404 | Unknown path, or a file, video job,
                response or generation that belongs to another workspace,
                including one a request refers to. On `/v1/generation`, also a
                call that recorded no stats (a failed call, for example) or a
                streamed call that is still running. |

                | `not_ready` | 404 or 502 | `/v1/generation` found the call,
                but its stats are not available yet (404) or could not be read
                (502). |

                | `upstream_unavailable` | 502 | The model did not answer, or
                returned no audio. |

                | `catalog_unavailable` | 502 or 503 | The model catalog could
                not be read: 502 from the catalog listings, 503 from `GET
                /v1/models/public`. Retry shortly. |

                | `internal_error` | 500 | Unexpected error. |
            param:
              type: 'null'
            predev:
              $ref: '#/components/schemas/GatewayErrorDetails'
    GatewayErrorDetails:
      type: object
      description: Extra fields for some error codes; an empty object for the rest.
      properties:
        credits_remaining:
          type: number
          description: >-
            Workspace balance. Sent with `insufficient_credits` and
            `subscription_required`.
        estimated_credits:
          type: number
          description: >-
            Estimated credits the request needs. Sent with
            `insufficient_credits`.
        trial_credits_used:
          type: number
          description: >-
            Credits the free trial has spent on AI calls. Sent with
            `subscription_required`.
        topup_url:
          type: string
          format: uri
          description: Where to add credits or subscribe.
        retry_after:
          type: integer
          description: Seconds to wait. Also sent as the `Retry-After` header.
        available_models:
          type: array
          items:
            type: string
          description: >-
            Speech and music model ids. Sent with `invalid_request` from
            `/v1/audio/speech`.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          examples:
            missing_api_key:
              summary: No key sent
              value:
                error:
                  message: >-
                    Send your pre.dev API key as `Authorization: Bearer <key>`
                    or `x-api-key`. Copy it from Integrations → Built-in:
                    https://pre.dev/projects/integrations
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  predev: {}
            invalid_api_key:
              summary: Unknown or retired key
              value:
                error:
                  message: Invalid API key
                  type: authentication_error
                  code: invalid_api_key
                  param: null
                  predev: {}
    AuthFailures:
      description: >-
        More than 30 failed key attempts from this IP address in the current
        minute.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              message: >-
                Too many failed API key attempts from this address. Try again in
                a minute.
              type: rate_limit_error
              code: too_many_auth_failures
              param: null
              predev:
                retry_after: 60
    ServerError:
      description: Unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              message: The pre.dev AI gateway hit an unexpected error.
              type: server_error
              code: internal_error
              param: null
              predev: {}
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 12
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: pdk_ API key
      description: >-
        The workspace API key (`pdk_…`) from Integrations → Built-in in the
        pre.dev dashboard.
    xApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Alternative to `Authorization: Bearer`. The Anthropic SDKs send this
        header.

````

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