Run and observe

You have a task. Run it with one POST, read the structured response and the metrics that come with it, then fetch the recorded run back over the API. The examples reuse the RB_TOKEN, RB_ORG, and RB_PROJECT variables from Create a task; set RB_TASK to the id you saved there.

$
export RB_TASK="{task_id}"

Run the task

Send the task’s inputs in a task_input object. Its keys match the {placeholder} variables in the task’s prompt — here, customer_review.

$
curl -X POST https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task/$RB_TASK/run \
>
  -H "Authorization: Bearer $RB_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "task_input": {
>
      "customer_review": "My toaster exploded during breakfast, sending flaming bread across the kitchen! On the bright side, I have discovered a new way to heat the whole house. But seriously, this is a fire hazard."
>
    }
>
  }'

This task runs on text alone, so image_match is false and image_description is "N/A". To exercise image verification, create the task with a vision file_input_mode (such as "image") and attach a file on every run — either base64 in a task_files array or as multipart form data. See Run tasks via the API.

Read the response

Your model output is in the response field. Everything else is metadata about the run.

1
{
2
  "task_id": "0195d1ff-1f05-437a-95ac-6de8969cb47b",
3
  "task_revision_id": "0195d1ff-1f42-f14e-8b65-641baf9dc32e",
4
  "response": {
5
    "sentiment": "negative",
6
    "image_match": false,
7
    "image_description": "N/A"
8
  },
9
  "run_data": {
10
    "submitted": {
11
      "customer_review": "My toaster exploded during breakfast..."
12
    }
13
  },
14
  "files": [],
15
  "id": "0195d207-32bb-d03d-cfdc-f4516e9222c8",
16
  "created": "2025-03-26T10:37:15.687874Z",
17
  "input_tokens": 826,
18
  "output_tokens": 73,
19
  "total_tokens": 899,
20
  "input_processor_timing": 0.0002221050017396919,
21
  "llm_call_timing": 2.371594352996908,
22
  "charged_credits": "4"
23
}

The response also carries two headers worth keeping: x-task-run-id (this run’s id) and x-task-revision-id (the revision that served it).

Understand the metrics

Tokens

Timing

input_processor_timing covers work before the model call: URL fetching, document extraction, image preprocessing, and retrieval from a collection. llm_call_timing is the model inference itself and is usually the largest component of total latency.

Credits

charged_credits is what the run cost. The two levers are the model (higher-end models cost more per token) and the token count (both input and output). To reduce cost, compare model quality against credit consumption, trim prompts, and keep output concise.

Fetch the run back

Every run is recorded. Fetch a single run by its id, or list a task’s runs — observation is a plain GET.

$
curl https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task/$RB_TASK/run/{run_id} \
>
  -H "Authorization: Bearer $RB_TOKEN"

$
curl "https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task/$RB_TASK/run?page_limit=20" \
>
  -H "Authorization: Bearer $RB_TOKEN"

The list response is a paginated envelope ({ "pagination": {...}, "results": [...] }) — see Errors & pagination. The same runs are also visible in your dashboard, but everything you need to observe them is available over the API.

What’s next