Skip to main content
API variables allow your prompts to interact with external systems in real-time. They fetch data from external HTTP endpoints at runtime, transforming static prompts into dynamic, data-driven workflows.

​
How It Works

API variables enable seamless integration with external services:
  1. Define the Request: Set the URL, HTTP method, headers, and body for your API call
  2. Map to Dataset: If you have linked dataset on playground, use placeholders like {{userId}} within the API configuration. These are automatically resolved from your dataset columns at runtime
  3. Execution: The system performs the HTTP request and replaces the variable in your prompt with the API response

​
Configuration Details

API variables support comprehensive HTTP request configuration:
FeatureSupported Options / Limits
HTTP MethodsGET, POST, PUT, PATCH, DELETE
Injection PointsURL, Headers, Query Params, Request Body
Data TypesHandles JSON, Plain Text, Images, and PDFs
SecurityUse secretHeaders to obfuscate sensitive keys/tokens
Reliability30s timeout; 3 retries with exponential backoff (starting at 1s)

​
Dataset Integration

When API variables are linked to datasets, they function as Dynamic Columns:
  • Row-Level Execution: Each row in your dataset triggers its own unique API request
  • Variable Resolution: Placeholders in your API configuration (like {{userId}} in the URL) are replaced with values from the corresponding dataset row
  • Persistence: Results are stored within the dataset cells and can be used for subsequent evaluations

​
Example

If your dataset has a userId column and your API variable is configured with: 
URL: https://api.example.com/v1/details/{{userId}}
Each row will make a unique API call using that row’s userId value.

​
Execution Behavior

  • Sequential vs. Parallel: API variables that depend on other variables run sequentially, while independent API variables run in parallel
  • Timeout: Each API request has a 30-second timeout
  • Retries: Failed requests are automatically retried up to 3 times with exponential backoff (starting at 1 second)

​
Error Handling

Error TypeCauseResult
Missing ColumnVariable references a non-existent dataset columnExecution fails before the run starts
API Failure4xx/5xx errors or timeoutParent prompt fails; error propagates
Invalid URLMalformed URL after variable resolutionAPI request fails

​
Best Practices

  • Security: Always mark Authorization tokens and API keys as secretHeaders to prevent them from being exposed in logs
  • Naming: Use descriptive names (e.g., {{user_purchase_history}} instead of {{var1}})
  • Testing: Test API endpoints independently before integrating them into your prompts
Variable names must follow specific naming rules. See Variable Name Constraints for detailed information about allowed characters and naming conventions.