Run Task

GA
POST

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
  3. Execution metadata (tokens, timing, etc.)
  4. Support for file uploads when required

Required:

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

Optional:

  • Specific revision_id for testing or comparison
  • Custom execution parameters

The response includes:

  • Structured output matching the task’s output_format
  • Execution metadata (tokens used, timing)
  • Input data for audit purposes
  • References to any processed images

Path parameters

org_idstringRequired

The unique identifier of the organization.

project_idstringRequired

The unique identifier of the project.

task_idstringRequired

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.

Request

This endpoint expects a multipart form containing an optional file.
task_inputstringRequired

The input data for the Task in JSON format. Must include values for all dynamic parameters referenced in the Task’s user_prompt. Example: {"text": "analyze this content", "max_length": 100}

Not required if image_required=true and there are no dynamic parameters in the prompt.

task_filefileOptional

Response

Successful Response

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.

createddatetime

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_timingdoubleOptional

The execution time for the TaskRun in seconds.

llm_call_timingdoubleOptional

The execution time for the TaskRun in seconds.

Errors

Built with