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_format (JSON, image, or audio)
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

Required:

Input parameters as defined in the task’s user_prompt
Image file if task has image_required=true

Optional:

Specific 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

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_format (JSON, image, or audio) 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 Required: - Input parameters as defined in the task's user_prompt - Image file if task has image_required=true Optional: - Specific 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

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.

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.

responsemap from strings to any

The structured response from the Task execution.

run_dataobject

Additional data about the Task execution, including submitted inputs and processed files.

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.

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

reporting_groupobject or null

The reporting group associated with this task run

Errors

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_format (JSON, image, or audio)
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

Required:

Input parameters as defined in the task’s user_prompt
Image file if task has image_required=true

Optional:

Specific 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

1	import requests
2
3	url = "https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/run"
4
5	headers = {"Authorization": "Bearer <token>"}
6
7	response = requests.post(url, headers=headers)
8
9	print(response.json())

1	{
2	"task_id": "019011e6-e530-3aca-6cf7-2973387c255d",
3	"task_revision_id": "0190a234-8dc6-6d08-aea9-928fcecad8f1",
4	"response": {
5	"compliance": false,
6	"hint": "The image is not suitable for authentication and onboarding checks. Please ensure the photo is a clear, passport-style image with a plain background, good lighting, and no accessories like sunglasses.",
7	"match": false,
8	"rationale": "The image does not meet the requirements for a passport-style photo. The person is wearing sunglasses, and the background is not plain."
9	},
10	"run_data": {
11	"submitted": {
12	"description": "brown hair, blue sweater",
13	"image": "profile_photo.jpg"
14	},
15	"files": [
16	"profile_photo.jpg"
17	]
18	},
19	"id": "0190a234-cb74-6342-dec6-4be8f73f0c9f",
20	"created": "2024-07-11T14:31:21.989219",
21	"input_tokens": 295,
22	"output_tokens": 58,
23	"total_tokens": 353,
24	"input_processor_timing": 0.35,
25	"llm_call_timing": 2.45,
26	"charged_credits": "2.82"
27	}