Skip to main content

​
Overview

This endpoint allows you to execute a specific workflow by providing its ID and required input parameters. The response is returned after the model finishes generating — ideal for server-side integrations where you don’t need real-time streaming.

​
Endpoint

  • HTTP Method: POST
  • URL: /api/v1/run/{workflow_id}
Replace {workflow_id} with the actual workflow ID (e.g. wf_abc123).

​
Features

Full Response

Receive the complete generated output in a single JSON response.

Bearer Key Auth

Authenticate with your API secret key via the Authorization header.

Web Search Citations

Automatically receive source citations when the model uses web search.

Rate Limit Headers

Monitor your usage with rate limit headers in every response.

​
Authentication

Requires a Bearer token in the Authorization header. 
Authorization: Bearer YOUR_API_KEY

​
Request

Path Parameters
NameRequiredTypeDescription
workflow_idYesstringThe ID of the workflow to run (e.g. wf_abc123)
Request Body Content-Type: application/json Pass your workflow’s input variables as key/value pairs. The keys must match the variable names defined in your workflow template. 
{
  "story": "a story about a dog named charlie"
}

​
Example Request

curl --request POST \
     --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"story": "a story about a dog named charlie"}'

​
Response

A successful response returns the full generated text and optional citations: 
{
  "success": true,
  "result": "Once upon a time, there was a friendly dog named Charlie...",
  "citations": ["https://example.com/source"]
}
FieldTypeDescription
successbooleanAlways true on success
resultstringThe generated text output
citationsstring[]Optional. Web sources if the model used web search
Response Headers
HeaderDescription
x-ratelimit-limitYour rate limit per window
x-ratelimit-remainingRemaining requests in window

​
Error Responses

Missing or invalid API key.
{
  "error": "Unauthorized. Please provide a valid secret key.",
  "success": false
}
No credits remaining on the account.
{
  "error": "No credits remaining. Please add credits to continue using the service.",
  "success": false,
  "code": "invalid_billing"
}
Workflow not found or not published.
{
  "error": "Workflow not found",
  "success": false,
  "code": "workflow_not_found"
}
Rate limit exceeded.
{
  "error": "Rate limit exceeded",
  "success": false
}
Something went wrong during execution.
{
  "error": "Failed to run workflow",
  "success": false,
  "code": "internal_server_error"
}

​
Code Examples

import requests

url = "https://aitutor-api.vercel.app/api/v1/run/wf_abc123"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
data = {
    "story": "a story about a dog named charlie",
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch(
  "https://aitutor-api.vercel.app/api/v1/run/wf_abc123",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      story: "a story about a dog named charlie",
    }),
  }
);

const data = await response.json();
console.log(data.result);

curl --request POST \
     --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"story": "a story about a dog named charlie"}'

​
Additional Notes

  • Input Variables: The request body keys must exactly match the variable names in your workflow template (e.g. {{story}}).
  • Max Duration: Requests can run for up to 300 seconds before timing out.
  • Credits: Each successful run deducts credits from your organization’s balance based on token usage.
  • Streaming Alternative: If you need real-time output as it’s generated, use the Streaming Workflow endpoint instead.