Skip to main content
POST
/
prompts
/
{slug}
/
run
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"
  }'

{
  "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
}
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

​
Authorization
string
required
Bearer token with your API key: Bearer tr_your_api_key
​
slug
string
required
The prompt slug to run
​
variables
object
Key-value pairs for template variables. Must include all variables required by the prompt.
​
model
string
Override the default model (e.g., gpt-4o, claude-sonnet-4-20250514)
​
tags
string[]
Tags for filtering spans in the dashboard
​
userId
string
End user identifier for tracking
​
sessionId
string
Session identifier for grouping related spans
​
traceId
string
Group related spans together (session ID for multi-turn conversations)
​
parentSpanId
string
Link to parent span (creates a chain). When provided without traceId, the trace ID is inherited from the parent span.
​
messages
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.

​
Response

​
text
string
The generated text from the LLM
​
spanId
string
Unique identifier for this span
​
traceId
string
Session identifier (same as spanId if not part of session)
​
promptVersion
number
Version of the prompt that was used
​
latencyMs
number
Total request latency in milliseconds
​
usage
object
Token usage statistics
​
cost
number
Estimated cost in USD
​
finishReason
string
Why the model stopped generating: stop, max_tokens, or tool_calls
​
toolCalls
array
Tool calls made by the model (when the prompt has tools configured)
​
structuredOutput
object
Parsed JSON object when the prompt has an output schema configured. The output conforms to the JSON schema defined in the prompt settings.
​
messages
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.
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"
  }'

{
  "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
}

Authorizations

​
Authorization
string
header
required

API key starting with tr_

Path Parameters

​
slug
string
required

The prompt slug to run

Body

application/json
​
variables
object

Key-value pairs for template variables

​
model
string

Override the default model (e.g., gpt-4o, claude-sonnet-4-20250514)

​
tags
string[]

Tags for filtering spans in the dashboard

​
userId
string

End user identifier for tracking

​
sessionId
string

Session identifier for grouping related spans

​
traceId
string

Group related spans together (session ID for multi-turn conversations)

​
parentSpanId
string

Link to parent span (creates a chain)

​
messages
object[]

Full conversation messages for multi-turn (skips template rendering when provided)

Response

Successful response

​
text
string

The generated text from the LLM

​
spanId
string

Unique identifier for this span

​
traceId
string

Session identifier (same as spanId if not part of session)

​
promptVersion
integer

Version of the prompt that was used

​
latencyMs
integer

Total request latency in milliseconds

​
usage
object
​
cost
number

Estimated cost in USD

​
finishReason
enum<string> | null

Why the model stopped generating

Available options:
stop,
max_tokens,
tool_calls
​
toolCalls
object[] | null

Tool calls made by the model

​
structuredOutput
object

Parsed JSON when the prompt has an output schema configured

​
messages
object[]

Full conversation messages for multi-turn continuation (input messages + assistant response)