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

# Get Run

> Look up one agent run by the id sent on its `X-Mesh-Run-Id` request header.

An agent run spans many requests. Send the same run id on each of them and this
reports them as one unit: every hop in order, oldest first, and one spend figure
for the whole run.

`total_charged_usd` is what the run cost — the sum of what each request charged,
which is what the balance was debited. Attempts that were retried and requests
that failed charged nothing and so add nothing to it, and on a run served by your
own provider credential it is the platform fee rather than the model's price.

`events` includes the retried attempts, not only the request that served, so a
model that was tried and failed is visible rather than inferred. `attempts`
counts every row and `served_rows` the ones that served, so a long run reports
`truncated: true` once the trace reaches its cap and the totals still cover all
of it. `served_rows` is rows, not requests: one request that fans out internally
— a `/v1/compare` leg, an auto-routed classifier call, a memory or RAG lookup —
writes more than one of them.

Only requests that reached a model are here. One that was refused first — over a
rate limit, a spend cap, an unknown model — charges nothing and writes no usage
row, so it appears in `POST /v1/usage/rejections`, which takes the same `run_id`
— over roughly the last 90 days, that endpoint's own window and not this one's. It
reads whole monthly collections, so the edge of it is a month boundary, not a day.
A trace is resolvable for as long as its usage rows are kept; unlike
`GET /v1/usage/requests/{request_id}` it has no shorter window of its own.

Scoping matches `POST /v1/usage/events`: an API-key caller sees only the run's
requests made by that key; a JWT caller sees their own org, and a non-privileged
member only their own requests plus the teams they administer; an org admin key
reads its own org. A run id is yours to choose, so two accounts can pick the same
one — you are only ever shown your own requests, and a run id with none of them
is "not found" rather than a confirmation that it exists elsewhere.



## OpenAPI

````yaml /api/openapi.json get /v1/usage/runs/{run_id}
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/runs/{run_id}:
    get:
      tags:
        - Usage
      summary: Get Run
      description: >-
        Look up one agent run by the id sent on its `X-Mesh-Run-Id` request
        header.


        An agent run spans many requests. Send the same run id on each of them
        and this

        reports them as one unit: every hop in order, oldest first, and one
        spend figure

        for the whole run.


        `total_charged_usd` is what the run cost — the sum of what each request
        charged,

        which is what the balance was debited. Attempts that were retried and
        requests

        that failed charged nothing and so add nothing to it, and on a run
        served by your

        own provider credential it is the platform fee rather than the model's
        price.


        `events` includes the retried attempts, not only the request that
        served, so a

        model that was tried and failed is visible rather than inferred.
        `attempts`

        counts every row and `served_rows` the ones that served, so a long run
        reports

        `truncated: true` once the trace reaches its cap and the totals still
        cover all

        of it. `served_rows` is rows, not requests: one request that fans out
        internally

        — a `/v1/compare` leg, an auto-routed classifier call, a memory or RAG
        lookup —

        writes more than one of them.


        Only requests that reached a model are here. One that was refused first
        — over a

        rate limit, a spend cap, an unknown model — charges nothing and writes
        no usage

        row, so it appears in `POST /v1/usage/rejections`, which takes the same
        `run_id`

        — over roughly the last 90 days, that endpoint's own window and not this
        one's. It

        reads whole monthly collections, so the edge of it is a month boundary,
        not a day.

        A trace is resolvable for as long as its usage rows are kept; unlike

        `GET /v1/usage/requests/{request_id}` it has no shorter window of its
        own.


        Scoping matches `POST /v1/usage/events`: an API-key caller sees only the
        run's

        requests made by that key; a JWT caller sees their own org, and a
        non-privileged

        member only their own requests plus the teams they administer; an org
        admin key

        reads its own org. A run id is yours to choose, so two accounts can pick
        the same

        one — you are only ever shown your own requests, and a run id with none
        of them

        is "not found" rather than a confirmation that it exists elsewhere.
      operationId: get_run
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            title: Run Id
        - in: header
          name: X-Mesh-Version
          required: false
          schema:
            type: string
            enum:
              - 2026-08
              - 2026-09
              - 2026-11
              - '2026-11-12'
            default: 2026-08
          example: '2026-11-12'
          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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunTraceOut'
        '404':
          description: No run with that id is visible to this caller
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    RunTraceOut:
      properties:
        run_id:
          type: string
          title: Run Id
        events:
          items:
            $ref: '#/components/schemas/UsageEventOut'
          type: array
          title: Events
        attempts:
          type: integer
          title: Attempts
        served_rows:
          type: integer
          title: Served Rows
        truncated:
          type: boolean
          title: Truncated
        total_charged_usd:
          type: string
          title: Total Charged Usd
        total_tokens:
          type: integer
          title: Total Tokens
        first_at:
          type: string
          title: First At
        last_at:
          type: string
          title: Last At
      type: object
      required:
        - run_id
        - events
        - attempts
        - served_rows
        - truncated
        - total_charged_usd
        - total_tokens
        - first_at
        - last_at
      title: RunTraceOut
      description: >-
        One agent run: its requests as an ordered trace, and its spend as one
        figure.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UsageEventOut:
      properties:
        id:
          type: string
          title: Id
        key_id:
          type: string
          title: Key Id
        key_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Key Label
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        end_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: End User Id
        request_id:
          type: string
          title: Request Id
        model:
          type: string
          title: Model
        model_name:
          type: string
          title: Model Name
        model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Provider
        stream:
          type: boolean
          title: Stream
        prompt_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Prompt Tokens
        completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completion Tokens
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
        cost_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cost Usd
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
        tokens_per_second:
          anyOf:
            - type: number
            - type: 'null'
          title: Tokens Per Second
        provider_latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Provider Latency Ms
        platform_latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Platform Latency Ms
        ttft_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ttft Ms
        status:
          type: string
          title: Status
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        error_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Category
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        failure_stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Stage
        service_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Tier
        cost_breakdown:
          anyOf:
            - $ref: '#/components/schemas/CostBreakdownOut'
            - type: 'null'
        created_at:
          type: string
          title: Created At
        images_generated:
          anyOf:
            - type: integer
            - type: 'null'
          title: Images Generated
        model_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Type
        is_byok:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Byok
        byok_key_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Byok Key Id
        byok_key_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Byok Key Label
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        fallback_triggered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Fallback Triggered
        platform_fee_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Platform Fee Usd
        image_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Image Tokens
        member_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Member Name
        member_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Member Email
        attempt_no:
          anyOf:
            - type: integer
            - type: 'null'
          title: Attempt No
        is_retry_attempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Retry Attempt
        routing_fallback:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Routing Fallback
        model_requested:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Requested
        tags:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Tags
        run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Id
        endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Endpoint
      type: object
      required:
        - id
        - key_id
        - key_label
        - request_id
        - model
        - model_name
        - model_provider
        - stream
        - prompt_tokens
        - completion_tokens
        - total_tokens
        - cost_usd
        - latency_ms
        - tokens_per_second
        - status
        - error_code
        - created_at
      title: UsageEventOut
    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
    CostBreakdownOut:
      properties:
        lines:
          items:
            $ref: '#/components/schemas/CostLineOut'
          type: array
          title: Lines
        subtotal_usd:
          type: string
          title: Subtotal Usd
        rounding_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Rounding Usd
        discount_pct:
          anyOf:
            - type: string
            - type: 'null'
          title: Discount Pct
        discount_usd:
          type: string
          title: Discount Usd
        tool_fee_usd:
          type: string
          title: Tool Fee Usd
        cost_usd:
          type: string
          title: Cost Usd
      type: object
      required:
        - lines
        - subtotal_usd
        - discount_pct
        - discount_usd
        - tool_fee_usd
        - cost_usd
      title: CostBreakdownOut
      description: >-
        How `cost_usd` was reached. Rates are our sell rates; nothing upstream
        is exposed.
    CostLineOut:
      properties:
        kind:
          type: string
          title: Kind
        quantity:
          anyOf:
            - type: string
            - type: 'null'
          title: Quantity
        unit:
          anyOf:
            - type: string
              enum:
                - tokens
                - images
                - megapixels
                - seconds
                - characters
                - utf8_bytes
                - calls
                - requests
            - type: 'null'
          title: Unit
        rate_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Rate Usd
        tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens
        rate_per_1m_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Rate Per 1M Usd
        amount_usd:
          type: string
          title: Amount Usd
        modifiers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Modifiers
        charged:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Charged
      type: object
      required:
        - kind
        - amount_usd
      title: CostLineOut
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Enter your MeshAPI key (`rsk_...`) or, for the admin-keys endpoints, a
        dashboard session token — sent as `Authorization: Bearer <token>`.

````

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