> ## 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.

# Generation stats

> Stats and the credits charged for one call, by its pdg- id. Use it for streamed calls.



## OpenAPI

````yaml api-reference/ai-gateway.openapi.json GET /v1/generation
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/generation:
    get:
      tags:
        - Usage
      summary: Get generation stats
      description: >-
        Stats and the credits charged for one call, by the `id` from its
        response body (`pdg-…`). Use it for streamed calls, which do not return
        the credits header. Stats can take a few seconds to appear after a call;
        retry on `not_ready`. Only this workspace's calls are visible.
      operationId: getGeneration
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          example: pdg-043293a6-d1a8-4695-81fe-603ad4661ebb
      responses:
        '200':
          description: The stats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
              example:
                data:
                  id: pdg-043293a6-d1a8-4695-81fe-603ad4661ebb
                  model: anthropic/claude-sonnet-5
                  created_at: '2026-09-27T12:00:00.000Z'
                  streamed: true
                  cancelled: false
                  latency: 1830
                  generation_time: 1620
                  finish_reason: stop
                  tokens_prompt: 21
                  tokens_completion: 14
                  native_tokens_prompt: 23
                  native_tokens_completion: 14
                  native_tokens_reasoning: 0
                  native_tokens_cached: 0
                  num_media_prompt: 0
                  num_media_completion: 0
                  num_search_results: 0
                  credits: 0.005
        '400':
          description: '`id` is missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message: '`id` is required.'
                  type: invalid_request_error
                  code: missing_id
                  param: null
                  predev: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such call in this workspace, or its stats are not ready yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              examples:
                not_found:
                  summary: Unknown id
                  value:
                    error:
                      message: No generation with that id belongs to this workspace.
                      type: not_found_error
                      code: not_found
                      param: null
                      predev: {}
                not_ready:
                  summary: Stats not ready yet
                  value:
                    error:
                      message: >-
                        Generation stats are not available yet. Retry in a few
                        seconds.
                      type: not_found_error
                      code: not_ready
                      param: null
                      predev: {}
        '429':
          $ref: '#/components/responses/AuthFailures'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          description: Stats could not be read. Retry in a few seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message: >-
                    Generation stats are not available yet. Retry in a few
                    seconds.
                  type: server_error
                  code: not_ready
                  param: null
                  predev: {}
components:
  schemas:
    Generation:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - credits
          properties:
            id:
              type: string
            model:
              type: string
            created_at:
              type: string
              format: date-time
            streamed:
              type:
                - boolean
                - 'null'
            cancelled:
              type:
                - boolean
                - 'null'
            latency:
              type:
                - number
                - 'null'
              description: Total time in milliseconds.
            generation_time:
              type:
                - number
                - 'null'
              description: Generation time in milliseconds.
            finish_reason:
              type:
                - string
                - 'null'
            tokens_prompt:
              type:
                - integer
                - 'null'
            tokens_completion:
              type:
                - integer
                - 'null'
            native_tokens_prompt:
              type:
                - integer
                - 'null'
              description: Counted by the model's own tokenizer.
            native_tokens_completion:
              type:
                - integer
                - 'null'
            native_tokens_reasoning:
              type:
                - integer
                - 'null'
            native_tokens_cached:
              type:
                - integer
                - 'null'
            native_tokens_completion_images:
              type:
                - integer
                - 'null'
            num_media_prompt:
              type:
                - integer
                - 'null'
            num_media_completion:
              type:
                - integer
                - 'null'
            num_input_audio_prompt:
              type:
                - integer
                - 'null'
            num_search_results:
              type:
                - integer
                - 'null'
            credits:
              type:
                - number
                - 'null'
              description: Credits charged for the call.
    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. |

                | `not_ready` | 404 or 502 | Generation stats are not available
                yet. |

                | `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.

````