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

# Get a prompt run by ID

> Retrieves the current state of a prompt run, including status, outputs, token usage, cost, and errors. Poll this endpoint after receiving a webhook notification, or use it to check the status of a run in progress.



## OpenAPI

````yaml /openapi.json get /api/v1/promptruns/{id}
openapi: 3.1.1
info:
  title: PromptJuggler
  description: PromptJuggler API
  version: 1.0.0
servers:
  - url: https://promptjuggler.com
security:
  - Bearer: []
tags:
  - name: Prompts
    description: Fetch prompts and revisions.
  - name: Prompt Runs
    description: Execute published prompts and retrieve results.
  - name: Workflow Runs
    description: Execute multi-step workflows and retrieve results.
  - name: Knowledge Bases
    description: Upload and manage documents used for retrieval-augmented generation.
paths:
  /api/v1/promptruns/{id}:
    get:
      tags:
        - Prompt Runs
      summary: Get a prompt run by ID
      description: >-
        Retrieves the current state of a prompt run, including status, outputs,
        token usage, cost, and errors. Poll this endpoint after receiving a
        webhook notification, or use it to check the status of a run in
        progress.
      operationId: get_prompt_run
      parameters:
        - name: id
          in: path
          description: Prompt run ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Prompt Run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptRun'
        '401':
          description: Missing or invalid API key
        '403':
          description: No active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Prompt run not found
      x-codeSamples:
        - lang: PHP
          label: PromptJuggler PHP SDK
          source: $run = $pj->getPromptRun('01J...');
        - lang: TypeScript
          label: PromptJuggler TypeScript SDK
          source: const run = await pj.getPromptRun('01J...');
        - lang: Python
          label: PromptJuggler Python SDK
          source: run = pj.get_prompt_run('01J...')
        - lang: Java
          label: PromptJuggler Java SDK
          source: PromptRun run = pj.getPromptRun("01J...");
        - lang: Go
          label: PromptJuggler Go SDK
          source: run, err := pj.GetPromptRun(ctx, "01J...")
components:
  schemas:
    PromptRun:
      description: Prompt run status and result.
      required:
        - id
        - status
        - createdAt
      properties:
        id:
          description: Prompt run ID.
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RunStatus'
          description: Current run status.
        createdAt:
          description: Timestamp when the run was created.
          type: string
          format: date-time
        finishedAt:
          description: Timestamp when the run finished. Null while the run is pending.
          type:
            - string
            - 'null'
          format: date-time
        output:
          description: LLM output text. Null while pending or when the run failed.
          type:
            - string
            - 'null'
        error:
          description: Error message if the run failed. Null on success.
          type:
            - string
            - 'null'
        tokenUsage:
          description: >-
            Token usage for the successful run. Null while pending or when the
            run failed.
          oneOf:
            - $ref: '#/components/schemas/TokenUsage'
            - type: 'null'
        cost:
          description: Cost breakdown for the run. Null while pending.
          oneOf:
            - $ref: '#/components/schemas/RunCost'
            - type: 'null'
      type: object
    ErrorResponse:
      description: Error response.
      required:
        - error
      properties:
        error:
          description: Error message.
          type: string
      type: object
    RunStatus:
      type: string
      enum:
        - pending
        - completed
        - failed
    TokenUsage:
      required:
        - input
        - inputCached
        - output
        - reasoning
        - total
      properties:
        input:
          type: integer
        inputCached:
          type: integer
        output:
          type: integer
        reasoning:
          type: integer
        total:
          type: integer
        serviceTier:
          $ref: '#/components/schemas/ServiceTier'
      type: object
    RunCost:
      required:
        - success
        - retries
        - total
      properties:
        success:
          $ref: '#/components/schemas/ModelCost'
        retries:
          $ref: '#/components/schemas/ModelCost'
        total:
          type: number
          format: float
      type: object
    ServiceTier:
      type: string
      enum:
        - auto
        - default
        - flex
        - priority
    ModelCost:
      required:
        - input
        - cachedInput
        - output
        - webSearch
        - total
      properties:
        input:
          type: number
          format: float
        cachedInput:
          type: number
          format: float
        output:
          type: number
          format: float
        webSearch:
          type: number
          format: float
        total:
          type: number
          format: float
      type: object
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````