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

# Run Prompt

> Execute a prompt and get the LLM response

Run a prompt with variable substitution and get the generated response. This endpoint handles template rendering, LLM API calls, and automatically logs a span.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer tr_your_api_key`
</ParamField>

<ParamField path="slug" type="string" required>
  The prompt slug to run
</ParamField>

<ParamField body="variables" type="object">
  Key-value pairs for template variables. Must include all variables required by the prompt.
</ParamField>

<ParamField body="model" type="string">
  Override the default model (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
</ParamField>

<ParamField body="version" type="integer">
  Run a specific prompt version. If omitted, the latest version is used. Useful for pinning a known-good version in production.
</ParamField>

<ParamField body="tags" type="string[]">
  Tags for filtering spans in the dashboard
</ParamField>

<ParamField body="userId" type="string">
  End user identifier for tracking
</ParamField>

<ParamField body="sessionId" type="string">
  Session identifier for grouping related spans
</ParamField>

<ParamField body="traceId" type="string">
  Group related spans together (session ID for multi-turn conversations)
</ParamField>

<ParamField body="parentSpanId" type="string">
  Link to parent span (creates a chain). When provided without `traceId`, the trace ID is inherited from the parent span.
</ParamField>

<ParamField body="messages" type="array">
  Full conversation messages for multi-turn tool calling. When provided, template rendering is skipped and these messages are sent directly to the LLM. Each message has `role` (system/developer/user/assistant/tool), `content`, and optionally `toolCallId`/`toolName` for tool result messages.
</ParamField>

## Response

<ResponseField name="text" type="string">
  The generated text from the LLM
</ResponseField>

<ResponseField name="spanId" type="string">
  Unique identifier for this span
</ResponseField>

<ResponseField name="traceId" type="string">
  Session identifier (same as spanId if not part of session)
</ResponseField>

<ResponseField name="promptVersion" type="number">
  Version of the prompt that was used
</ResponseField>

<ResponseField name="latencyMs" type="number">
  Total request latency in milliseconds
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics

  <Expandable title="Usage object">
    <ResponseField name="inputTokens" type="number">
      Number of input tokens
    </ResponseField>

    <ResponseField name="outputTokens" type="number">
      Number of output tokens
    </ResponseField>

    <ResponseField name="totalTokens" type="number">
      Total tokens used
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cost" type="number">
  Estimated cost in USD
</ResponseField>

<ResponseField name="finishReason" type="string">
  Why the model stopped generating: `stop`, `max_tokens`, or `tool_calls`
</ResponseField>

<ResponseField name="toolCalls" type="array">
  Tool calls made by the model (when the prompt has tools configured)

  <Expandable title="ToolCall object">
    <ResponseField name="id" type="string">
      Unique identifier for the tool call
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the tool called
    </ResponseField>

    <ResponseField name="arguments" type="object">
      Arguments passed to the tool
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="structuredOutput" type="object">
  Parsed JSON object when the prompt has an output schema configured. The output conforms to the JSON schema defined in the prompt settings.
</ResponseField>

<ResponseField name="messages" type="array">
  Full conversation messages (rendered input + assistant response) for multi-turn continuation. Pass these back in the next request's `messages` field to continue the conversation.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.tracia.io/api/v1/prompts/welcome-email/run \
    -H "Authorization: Bearer tr_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "variables": {
        "name": "Alice",
        "product": "Tracia"
      },
      "tags": ["onboarding", "email"],
      "userId": "user_123"
    }'
  ```

  ```typescript SDK theme={null}
  const result = await tracia.prompts.run('welcome-email', {
    name: 'Alice',
    product: 'Tracia'
  }, {
    tags: ['onboarding', 'email'],
    userId: 'user_123'
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "text": "Dear Alice,\n\nWelcome to Tracia! We're thrilled to have you join our community...",
    "spanId": "sp_abc123xyz",
    "traceId": "tr_session789",
    "promptVersion": 3,
    "latencyMs": 1250,
    "usage": {
      "inputTokens": 45,
      "outputTokens": 120,
      "totalTokens": 165
    },
    "cost": 0.0049,
    "finishReason": "stop",
    "toolCalls": null,
    "structuredOutput": null
  }
  ```

  ```json 200 Structured Output theme={null}
  {
    "text": "{\"sentiment\": \"positive\", \"confidence\": 0.95}",
    "spanId": "sp_def456uvw",
    "traceId": "tr_session789",
    "promptVersion": 2,
    "latencyMs": 890,
    "usage": {
      "inputTokens": 60,
      "outputTokens": 25,
      "totalTokens": 85
    },
    "cost": 0.0012,
    "finishReason": "stop",
    "toolCalls": null,
    "structuredOutput": {
      "sentiment": "positive",
      "confidence": 0.95
    }
  }
  ```

  ```json 400 Missing Variables theme={null}
  {
    "error": {
      "code": "MISSING_VARIABLES",
      "message": "Missing required variables: product"
    }
  }
  ```

  ```json 400 No Provider Key theme={null}
  {
    "error": {
      "code": "MISSING_PROVIDER_KEY",
      "message": "No OpenAI API key configured. Add one in Settings > Providers."
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Prompt not found: welcome-email"
    }
  }
  ```

  ```json 500 Provider Error theme={null}
  {
    "error": {
      "code": "PROVIDER_ERROR",
      "message": "OpenAI error: Rate limit exceeded"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /prompts/{slug}/run
openapi: 3.1.0
info:
  title: Tracia API
  description: REST API for managing and running AI prompts with tracing
  version: 1.0.0
servers:
  - url: https://app.tracia.io/api/v1
    description: Production server
security:
  - bearerAuth: []
paths:
  /prompts/{slug}/run:
    post:
      tags:
        - Prompts
      summary: Run Prompt
      description: Execute a prompt and get the LLM response
      operationId: runPrompt
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: The prompt slug to run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties:
                    type: string
                  description: Key-value pairs for template variables
                model:
                  type: string
                  description: >-
                    Override the default model (e.g., `gpt-4o`,
                    `claude-sonnet-4-20250514`)
                version:
                  type: integer
                  description: Run a specific prompt version (uses latest if omitted)
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags for filtering spans in the dashboard
                userId:
                  type: string
                  description: End user identifier for tracking
                sessionId:
                  type: string
                  description: Session identifier for grouping related spans
                traceId:
                  type: string
                  description: >-
                    Group related spans together (session ID for multi-turn
                    conversations)
                parentSpanId:
                  type: string
                  description: Link to parent span (creates a chain)
                messages:
                  type: array
                  description: >-
                    Full conversation messages for multi-turn (skips template
                    rendering when provided)
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - developer
                          - user
                          - assistant
                          - tool
                      content:
                        type: string
                      tool_call_id:
                        type: string
                        description: >-
                          Required when role is tool - the ID of the tool call
                          being responded to
                      tool_name:
                        type: string
                        description: >-
                          Required when role is tool - the name of the tool that
                          was called
                      tool_calls:
                        type: array
                        description: Tool calls in assistant messages
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                              enum:
                                - function
                            function:
                              type: object
                              properties:
                                name:
                                  type: string
                                arguments:
                                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The generated text from the LLM
                  spanId:
                    type: string
                    description: Unique identifier for this span
                  traceId:
                    type: string
                    description: Session identifier (same as spanId if not part of session)
                  promptVersion:
                    type: integer
                    description: Version of the prompt that was used
                  latencyMs:
                    type: integer
                    description: Total request latency in milliseconds
                  usage:
                    type: object
                    properties:
                      inputTokens:
                        type: integer
                      outputTokens:
                        type: integer
                      totalTokens:
                        type: integer
                  cost:
                    type: number
                    description: Estimated cost in USD
                  finishReason:
                    type: string
                    enum:
                      - stop
                      - max_tokens
                      - tool_calls
                    nullable: true
                    description: Why the model stopped generating
                  toolCalls:
                    type: array
                    nullable: true
                    description: Tool calls made by the model
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        arguments:
                          type: object
                  structuredOutput:
                    type: object
                    nullable: true
                    description: >-
                      Parsed JSON when the prompt has an output schema
                      configured
                  messages:
                    type: array
                    description: >-
                      Full conversation messages for multi-turn continuation
                      (input messages + assistant response)
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum:
                            - system
                            - developer
                            - user
                            - assistant
                            - tool
                        content:
                          type: string
                        tool_call_id:
                          type: string
                        tool_name:
                          type: string
                        tool_calls:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              function:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  arguments:
                                    type: string
        '400':
          description: Bad request (missing variables or provider key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Provider error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key starting with `tr_`

````