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

# Query Rejections

> Requests refused before any model was called — rate limit, spend cap, balance,
model access (MESH-679).

These never reach usage logging, so they are absent from /v1/usage/events by
construction: a refusal has no tokens, no cost and no provider, and belongs in
the request log rather than the billing ledger. Served from the request log,
which has recorded them all along.

Same auth and scoping as /v1/usage/events — an rsk_ key sees only its own
refusals; a session token sees the org's, narrowed to the caller's own keys
unless they are an org or team admin.



## OpenAPI

````yaml /api/openapi.json post /v1/usage/rejections
openapi: 3.1.0
info:
  title: MeshAPI
  description: One key, all AI models.
  version: 0.1.0
servers:
  - url: https://api.meshapi.ai
security:
  - BearerAuth: []
paths:
  /v1/usage/rejections:
    post:
      tags:
        - Usage
      summary: Query Rejections
      description: >-
        Requests refused before any model was called — rate limit, spend cap,
        balance,

        model access (MESH-679).


        These never reach usage logging, so they are absent from
        /v1/usage/events by

        construction: a refusal has no tokens, no cost and no provider, and
        belongs in

        the request log rather than the billing ledger. Served from the request
        log,

        which has recorded them all along.


        Same auth and scoping as /v1/usage/events — an rsk_ key sees only its
        own

        refusals; a session token sees the org's, narrowed to the caller's own
        keys

        unless they are an org or team admin.
      operationId: query_rejections
      parameters:
        - in: header
          name: X-Mesh-Version
          required: false
          schema:
            type: string
            enum:
              - 2026-08
            default: 2026-08
          example: 2026-08
          description: >-
            Dated version of the API contract to pin this request to. Omit it
            and the request is served under `2026-08` — the oldest supported
            version, so an existing integration is never moved by a release. A
            malformed or unsupported value is rejected with `400
            invalid_api_version` rather than falling back silently. The version
            actually served is echoed as `X-Mesh-Version` on every response,
            including errors.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectionFilter'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejectionsPage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    RejectionFilter:
      properties:
        org_id:
          type: string
          title: Org Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        since:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Since
        until:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Until
        key_id:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Id
        failure_stage:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Failure Stage
        limit:
          type: integer
          maximum: 200
          minimum: 1
          title: Limit
          default: 50
        offset:
          type: integer
          minimum: 0
          title: Offset
          default: 0
      type: object
      required:
        - org_id
      title: RejectionFilter
      description: |-
        Mirrors UsageFilter's shape for the fields that apply to a refusal.

        No `model` or `status`: nothing was routed, and the status is implied.
    RejectionsPage:
      properties:
        rejections:
          items:
            $ref: '#/components/schemas/RejectionOut'
          type: array
          title: Rejections
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        by_stage:
          additionalProperties:
            type: integer
          type: object
          title: By Stage
          default: {}
      type: object
      required:
        - rejections
        - total
        - limit
        - offset
      title: RejectionsPage
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RejectionOut:
      properties:
        request_id:
          type: string
          title: Request Id
        created_at:
          type: string
          title: Created At
        key_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Key Id
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        failure_stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Stage
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        status_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Status Code
        path:
          anyOf:
            - type: string
            - type: 'null'
          title: Path
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
      type: object
      required:
        - request_id
        - created_at
        - key_id
        - model
        - failure_stage
        - error_code
        - status_code
        - path
        - latency_ms
      title: RejectionOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Enter your MeshAPI key (`rsk_...`) — sent as `Authorization: Bearer
        <key>`.

````