Run Task

Run a task with the specified inputs and receive structured output. This endpoint executes the task using its active revision(s) and returns the results. Key features: 1. Automatic revision selection based on traffic weights 2. Structured output matching the task's output modality: - `json`: Structured JSON responses - `image`: Generated image files (PNG, JPEG) - `audio`: Generated audio files - `pdf`: Formatted PDF documents - `text`: Plain text responses - `csv`: CSV data files 3. Execution metadata (tokens, timing, credits charged) 4. Support for file uploads when required 5. Automatic fallback to backup model on primary model failures 6. Optional manual fallback model triggering 7. Reporting group tracking for analytics and billing **Request Body:** ⚠️ **IMPORTANT**: The request body must use the `task_input` field (not `input_params`): ```json { "task_input": { "variable_name": "value to substitute in user_prompt" } } ``` The keys in `task_input` should match the `{{variable}}` placeholders defined in your task's `user_prompt`. For example, if your prompt contains `{{text}}` and `{{language}}`, your request should be: ```json { "task_input": { "text": "Hello world", "language": "Spanish" } } ``` **Required:** - `task_input` object with parameters matching the task's prompt variables - File upload when task `file_input_mode` is not `none` **Optional Body Fields:** - `task_reference` to attach your own tracking ID to this run - `task_files` for base64-encoded file uploads **Optional Query Parameters:** - `revision_id` or `revision_tag` for testing or comparison - `reporting_group` name for segmented analytics - `use_fallback_model` flag to manually trigger fallback The response includes: - Structured output matching the task's output_format - Execution metadata (tokens used, timing, credits charged) - Fallback model usage information if applicable - Input data for audit purposes - References to any processed files **Common Use Cases:** *A/B Testing Revisions:* Compare different prompt versions by explicitly specifying `revision_id` or `revision_tag` for each request, then analyze results. *Gradual Rollouts:* Configure traffic weights on revisions to gradually shift traffic from an old prompt to a new one while monitoring performance. *Fallback Model Strategy:* Use `use_fallback_model=true` to manually switch to the backup model during known primary model outages or rate limits. *Analytics Segmentation:* Pass `reporting_group` to track metrics by customer, feature, or experiment cohort for billing and performance analysis.