Run Task | Rightbrain Docs | Transform AI Ideas into Production Tasks

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:

Automatic revision selection based on traffic weights
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
Execution metadata (tokens, timing, credits charged)
Support for file uploads when required
Automatic fallback to backup model on primary model failures
Optional manual fallback model triggering
Reporting group tracking for analytics and billing

Request Body:

⚠️ IMPORTANT: The request body must use the task_input field (not input_params):

1 {
2   "task_input": {
3     "variable_name": "value to substitute in user_prompt"
4   }
5 }

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:

1 {
2   "task_input": {
3     "text": "Hello world",
4     "language": "Spanish"
5   }
6 }

Required:

task_input object with parameters matching the task’s prompt variables
Image file if task has image_required=true

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.

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 - Image file if task has `image_required=true` **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.

Authentication

AuthorizationBearer

Bearer token authentication using JWT tokens from Ory Kratos/Hydra

Path parameters

org_idstringRequiredformat: "uuid"

The unique identifier of the organization.

project_idstringRequiredformat: "uuid"

The unique identifier of the project.

task_idstringRequiredformat: "uuid"

The specific Task to reference.

Query parameters

revision_idstringOptionalformat: "uuid"

Optional Task Revision ID to use for execution. If not provided, an active revision will be selected based on traffic weights.

revision_tagstringOptional

Optional Task Revision Tag to use for execution. If not provided, an active revision will be selected based on traffic weights.

reporting_groupstringOptional<=64 characters

Optional reporting group name to associate with this task run

use_fallback_modelbooleanOptionalDefaults to false

If true, immediately use the fallback model instead of the primary model. Requires the task to have a fallback model configured.

Request

This endpoint expects an object.

task_inputmap from strings to anyRequired

Key-value pairs mapping variable names to their values. Keys must match the variable placeholders in your task’s user_prompt.

task_fileslist of objectsOptional

Optional base64-encoded files to include with the task run

task_referencestringOptional<=64 characters

Optional reference ID for tracking this task run

Response

Task executed successfully

task_idstringformat: "uuid"

The unique identifier of the Task associated with this run.

task_revision_idstringformat: "uuid"

The unique identifier of the Task Revision associated with this run.

responsestring or map from strings to any

The structured response from the Task execution.

run_dataobject

Additional data about the Task execution, including submitted inputs.

idstringformat: "uuid"

The unique identifier of the Task Run.

createdstring

The timestamp when the Task Run was created.

input_tokensinteger

The number of tokens submit as input to the model.

output_tokensinteger

The number of tokens generated and output by the model.

total_tokensinteger

The total token usage for the TaskRun.

input_processor_timingdouble or null

The execution time for the TaskRun in seconds.

llm_call_timingdouble or null

The execution time for the TaskRun in seconds.

charged_creditsstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"

The total credits charged for the TaskRun.

fileslist of objects or null

List of file metadata objects with enriched information including download URLs.

is_errorboolean or nullDefaults to false

llm_retriesinteger or nullDefaults to 0

Number of retry attempts made during LLM execution.

used_fallback_modelboolean or nullDefaults to false

Whether the fallback model was used

primary_failure_reasonstring or null

Reason the primary model failed

fallback_llm_model_idstring or nullformat: "uuid"

Fallback model that was used

user_idstring or nullformat: "uuid"

The unique identifier of the User who executed the task.

reporting_group_idstring or nullformat: "uuid"

The ID of the reporting group to associate with this task run

referencestring or null<=64 characters

An optional reference identifier for this task run

context_idstring or null<=64 characters

An optional context ID for grouping related task runs

reporting_groupobject or null

The reporting group associated with this task run

Errors