> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/v-1/docs/quickstart/run-and-observe/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Run and observe

> Run a Rightbrain task via the API, interpret the response — output, tokens, timing, credits, files — and fetch the recorded run back with GET.

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](/docs/quickstart/create-a-task); set `RB_TASK` to the `id` you saved there.

```bash
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`.

> **Warning**
>
> The field is `task_input`, not `input_params`. A request without `task_input` fails validation.

**`cURL`**

```bash title="cURL"
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."
    }
  }'
```

**`Python`**

```python title="Python"
import os, requests

base = f"https://app.rightbrain.ai/api/v1/org/{os.environ['RB_ORG']}/project/{os.environ['RB_PROJECT']}"
headers = {"Authorization": f"Bearer {os.environ['RB_TOKEN']}"}

payload = {
    "task_input": {
        "customer_review": "My toaster exploded during breakfast, sending flaming bread across the kitchen!"
    }
}

run = requests.post(f"{base}/task/{os.environ['RB_TASK']}/run", headers=headers, json=payload).json()
print(run["response"])
```

**`TypeScript`**

```typescript title="TypeScript"
const base = `https://app.rightbrain.ai/api/v1/org/${process.env.RB_ORG}/project/${process.env.RB_PROJECT}`;

const response = await fetch(`${base}/task/${process.env.RB_TASK}/run`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RB_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    task_input: {
      customer_review: "My toaster exploded during breakfast, sending flaming bread across the kitchen!",
    },
  }),
});

const run = await response.json();
console.log(run.response);
```

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](/docs/api/run-tasks#attach-files).

## Read the response

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

```json
{
  "task_id": "0195d1ff-1f05-437a-95ac-6de8969cb47b",
  "task_revision_id": "0195d1ff-1f42-f14e-8b65-641baf9dc32e",
  "response": {
    "sentiment": "negative",
    "image_match": false,
    "image_description": "N/A"
  },
  "run_data": {
    "submitted": {
      "customer_review": "My toaster exploded during breakfast..."
    }
  },
  "files": [],
  "id": "0195d207-32bb-d03d-cfdc-f4516e9222c8",
  "created": "2025-03-26T10:37:15.687874Z",
  "input_tokens": 826,
  "output_tokens": 73,
  "total_tokens": 899,
  "input_processor_timing": 0.0002221050017396919,
  "llm_call_timing": 2.371594352996908,
  "charged_credits": "4"
}
```

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). The field-by-field reference for the run object is in [Run tasks via the API](/docs/api/run-tasks#response).

## Understand the metrics

### Tokens

| Input tokens grow with                                                 | Output tokens grow with               |
| ---------------------------------------------------------------------- | ------------------------------------- |
| User and system prompt length                                          | Complexity of the output structure    |
| Input variable content size                                            | Verbosity of the model's responses    |
| Retrieved context, if using a [collection](/docs/concepts/collections) | Number of fields in the output format |

### 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`.

**`Fetch one run`**

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

**`List runs for the task`**

```bash title="List runs for the task"
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](/docs/api/errors-and-pagination).

#### [Observability and audit](/docs/production/observability)

How runs, telemetry, and the audit log fit together.

## What's next

#### [Build your first agent](/docs/quickstart/first-agent)

Attach this task to an agent and run it with streaming.

#### [Run tasks via the API](/docs/api/run-tasks)

Files, revision selection, reporting groups, and fallbacks.

> Build reliable AI agents that run inside your existing tools and workflows. Rightbrain developer documentation.