> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Create and inspect agent runs via the API

<Note>
  Outbound calling is temporarily disabled. Use the [browser tester](/getting-started/quickstart) or [incoming calls](/integrations/telephony/inbound) to test your agent. The reference below does not enable outbound calling.
</Note>

| Method | Endpoint                                 | Quick Link                                                                          |
| ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `POST` | `/public/agent/{uuid}`                   | [Trigger an outbound agent run by API Trigger node](/api-reference/runs/trigger)    |
| `POST` | `/public/agent/workflow/{workflow_uuid}` | [Trigger an outbound agent run by Agent UUID](/api-reference/runs/trigger-workflow) |
| `GET`  | `/workflow/{workflow_id}/runs/{run_id}`  | [Retrieve agent run details](/api-reference/runs/get-run)                           |

## Choose the right public run route

Bandwidth Agent Builder exposes two public outbound agent run route families. They are **not**
interchangeable, even though both path parameters look like UUIDs.

| Use this when                                                                                                  | Production route                         | Test route                                    | Identifier you pass                                                                   |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
| You added an **[API Trigger node](/voice-agent/api-trigger)** to the workflow and want to execute that trigger | `/public/agent/{uuid}`                   | `/public/agent/test/{uuid}`                   | The trigger UUID (`trigger_path`) from the API Trigger node                           |
| You want to execute the workflow by its stable **Agent UUID** instead of a trigger node                        | `/public/agent/workflow/{workflow_uuid}` | `/public/agent/test/workflow/{workflow_uuid}` | The workflow UUID from the agent's **[Agent UUID](/configurations/agent-uuid)** field |

<Note>
  Do not pass a workflow UUID to `/public/agent/{uuid}` and do not pass a trigger UUID
  to `/public/agent/workflow/{workflow_uuid}`. Bandwidth Agent Builder treats these as different
  identifier types and the request will fail if you mix them up.
</Note>

Once Bandwidth Agent Builder resolves the target agent, both route families behave the same:

* They accept the same request body
* They return the same response shape
* They require a Labs OAuth user access token with `super_user` and at least Editor access to the selected workspace
* They use the same telephony configuration selection rules

If you specifically need the API Trigger route, see [Trigger an outbound agent run by API Trigger node](/api-reference/runs/trigger). To execute by Agent UUID, see [Trigger an outbound agent run by Agent UUID](/api-reference/runs/trigger-workflow).

## Using initial context

`initial_context` passes runtime data into the agent at run time. Values are available as template variables in your agent's prompt using double-brace syntax.

```json theme={null}
{
  "initial_context": {
    "customer_name": "Jane",
    "appointment_date": "March 15"
  }
}
```

Your agent prompt can then reference `{{customer_name}}` and `{{appointment_date}}` and they will be substituted when the run starts.

## Run state

Run records use `state` (`initialized`, `running`, or `completed`) and `is_completed`. Completion describes execution; review call disposition and results to determine the outcome. See [calls and results](/core-concepts/calls-and-runs).