> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md).

# Runs

Browse conversation runs and best-effort projected framework history, inspect structural trajectories, and control channel-aware operator takeover by run ID.

The unified runs endpoint is the public browse surface for conversation runs across voice, SMS, WhatsApp, email, web, and iMessage, plus terminal framework runs that reached the durable projection. Framework-run projection is best-effort, so this endpoint is not a live or guaranteed-complete framework-run ledger. Use `kind=framework` to browse the projected framework history.

{% hint style="info" %}
Live voice entries combine retained conversation records with best-effort active-call visibility. Realtime-provider calls attempt to open a record at call start and finalize that same record at call end. Other voice paths can appear through the live listing before their retained record is available. Persistence or live-source failures can leave entries missing or stale, so the listing is not a complete audit ledger.
{% endhint %}

## List Runs

SDK: `client.runs.list(params)`

Returns a paginated, newest-first list of conversation runs and projected terminal framework runs under one contract. Voice runs take `started_at` and `ended_at` from the call's start and end and sort by the call start. A text run starts at the conversation's creation. A finished text run ends at its close, or when the session that finished it ended. With no recorded end time, it ends at its last update.

An ended conversation run carries how it finished in `completion_reason`, `final_state`, and `duration_seconds`. A voice run reports the call's own values. A text conversation that reaches a terminal Context Graph state records `completion_reason` `completed`, the state it ended in as `final_state`, and its time from creation to that end as `duration_seconds`. A text conversation [closed](https://docs.concurrence.com/developer-guide/platform-api/conversations.md#close-a-conversation) through the API or by `force_new` records `completion_reason` `closed`, its time from creation to the close, and `final_state`, the Context Graph state it was in, when known. These fields are `null` on a live run and on a run that recorded none, such as a text conversation closed because its use case was rebound to another service.

Use `run_id` for run-scoped operations. A voice run's `source_call_sid` is a separate, opaque call handle that can be a UUID-shaped reference or a carrier-style value. Preserve the returned string without parsing its format. See [Calls](https://docs.concurrence.com/developer-guide/platform-api/conversations/calls.md).

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Authentication

Workspace API key (bearer token) or operator identity token. The bearer's workspace must match the path workspace.

### Status Mapping

The `status` field on each run is a canonical value derived from the underlying source:

* **Framework runs**: Terminal status is projected on a best-effort basis. A framework run may be absent if its terminal projection was not recorded.
* **Conversation runs (voice)**: An active call with no completion reason maps to `running`. A timed-out call maps to `timed_out`. Calls that ended due to errors or no audio map to `failed`. All other completed calls map to `completed`.
* **Conversation runs (non-voice)**: An open conversation updated within its channel's activity threshold maps to `running`. One that has been idle past the threshold maps to `dormant`: 5 minutes for web, 30 minutes for SMS, and 60 minutes for email, WhatsApp, and iMessage. The non-voice channels are SMS, WhatsApp, email, web, and iMessage. A dormant run is not live, has no `ended_at`, and is not eligible for takeover, and its next turn makes it `running` again. A text conversation that an operator holds stays `paused` for as long as the hold lasts, however long it is idle. The hold ends after 90 seconds without a renewal, and the run reads as `running` or `dormant` again by the rules above. Closed or completed conversations map to `completed`. Failed conversations map to `failed`.

The virtual `live` status filter expands to `running` + `paused`, returning active conversation runs. It does not include `dormant`, which has its own filter value. Projected framework history is terminal-only.

### What Ran a Run <a href="#what-ran-a-run" id="what-ran-a-run"></a>

Each conversation run reports what ran it, as its first session recorded it, so a run keeps saying what handled it after the service's configuration changes:

* `session_provider` is the runtime that handled the run: `gpt_realtime`, `eleven_realtime`, `gpt_live`, or `grok_voice` for a realtime voice family, or `concurrence` for a platform-managed call and for every text run.
* `manifest` holds the agent and Context Graph versions the session loaded, the version set it resolved them through, the model that wrote the replies (`llm_model`), the model that chose Context Graph hops (`navigation_model`, null on `gpt_realtime`, where the voice model requests state changes), the speech-to-text and text-to-speech vendors and models (null on a text run), and `platform_config_fingerprint`, one value for each combination of agent version, graph version, and model.
* The manifest also names the build the session ran on (`image_sha` and `runtime_release_id`), the sampling `temperature` its reply requests set (null where they set none, as on every voice call), hashes of the prompt templates its replies and navigation rendered from (`engage_prompt_template_hash` and `navigation_prompt_template_hash`, null on `gpt_realtime`), and the language its voice spoke (`tts_language`, null on a text run, and `multilingual` on a `gpt_realtime` call left to answer in the caller's language). The API reference describes its remaining fields.
* `manifest.program_kind` is `workflow` when the session ran its service's Context Graph, `direct` when it ran a [direct program](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md), and null when the run recorded neither. On a direct run, `manifest.program_digest` is a `sha256:` digest of the saved program, its instructions and tool specs, and the manifest's Context Graph id and version are null.
* `manifest.service_config_digest` is a `sha256:` digest of the whole service configuration the session received: the service, its agent and Context Graph versions, and the behaviors its version set pins. Any edit to that configuration changes it, where `platform_config_fingerprint` follows only the versions, the model, and the pins. Two runs that record the same digest received the same configuration. It is null when the session loaded none.

The manifest is what the run's first session started with. On a platform-managed call, a speech-to-text failover to another recognizer or a switch of the voice's language records it again, and the run keeps the last one. Nothing in either field is read from the service's current configuration. Both are null when the run recorded none, such as on a framework run, on a call that took the safe exit because it couldn't be set up, or on a text conversation before its first session starts. On a live platform-managed call, `manifest` is null until the call ends, and `session_provider` can be too. [Conversation detail](https://docs.concurrence.com/developer-guide/platform-api/conversations.md#get-conversation-detail) returns the same two fields.

### Filter by Channel <a href="#filter-by-channel" id="filter-by-channel"></a>

The `channel` filter on the run list and Runs Summary accepts `voice`, `sms`, `whatsapp`, `email`, `web`, and `imessage`, the channels a conversation run can carry. Repeat it to match any of several. Any other value returns `422`.

### Search Runs

Pass `search` for a case-insensitive substring match on a conversation run's entity name, caller ID, or phone number. The match runs before pagination, so every page holds only matching runs. Framework runs carry none of these fields and are excluded while `search` is set. It combines with the other filters using AND.

### Filter by Service

Pass `service_id` to list only the runs of one or more services, up to 100 IDs. Repeated values are ORed, and the filter combines with `kind`, `channel`, and `status` using AND. It applies to conversation runs and live voice runs before pagination, so every page holds only matching runs. Historical framework runs have no stored service, so they are excluded whenever `service_id` is set. The Runs Summary operation does not take this filter. In the Platform SDK, `client.runs.list({ serviceId: [...] })` sends the service filter.

### Filter by Source Conversation <a href="#filter-by-source-conversation" id="filter-by-source-conversation"></a>

Pass `source_conversation_id` to find the runs of one or more conversations, up to 100 IDs, such as the run of a Playground session, however old it is. Repeated values are ORed, and the filter combines with the other filters using AND before pagination. Runs without a source conversation are excluded while it is set: framework runs, and live calls whose conversation isn't recorded yet. The Runs Summary operation does not take this filter.

### Example Request

```
GET /v1/{workspace_id}/runs?limit=20&status=running&status=paused&kind=conversation&channel=voice
Authorization: Bearer {api_key}
```

### Example Response

```json
{
  "items": [
    {
      "run_id": "a1b2c3d4-...",
      "workspace_id": "w1x2y3z4-...",
      "kind": "conversation",
      "status": "running",
      "channel": "voice",
      "framework": null,
      "entity_id": "e1f2g3h4-...",
      "service_id": "s1t2u3v4-...",
      "started_at": "2026-07-15T14:30:00Z",
      "ended_at": null,
      "source_call_sid": "2c725f98-a9c6-4be2-8a48-6eb42d1f81cb",
      "source_conversation_id": "c1d2e3f4-...",
      "source_framework_run_id": null,
      "session_provider": "concurrence",
      "manifest": null
    }
  ],
  "has_more": true,
  "continuation_token": 20
}
```

### Error Responses

| Status                     | Condition                                                                                                                                                                                                                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403 Forbidden`            | Bearer workspace does not match the path workspace.                                                                                                                                                                                                                                            |
| `422 Unprocessable Entity` | Invalid query parameter, such as an invalid `continuation_token`, an unsupported `sort_by`, or more than 100 `service_id` or `source_conversation_id` values. A `sort_by` error lists the allowed values, `+started_at` and `-started_at`. An empty `continuation_token` reads the first page. |
| `502 Bad Gateway`          | Run data is temporarily unavailable.                                                                                                                                                                                                                                                           |

## Runs Summary

SDK: `client.runs.summary(params)`

Summarizes the same unified inventory. Repeated kind and channel filters use OR semantics, and a channel filter restricts results to conversation runs. `live` counts `running` and `paused` runs, and `dormant` counts idle open conversations, which are not live.

The summary excludes a live entry when the same call already has a running conversation record. Reads can still observe different moments during call startup or completion, so counts can briefly differ from the list. Reconcile individual run identifiers when an exact operational count is required.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/summary" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Get a Run

SDK: `client.runs.get(runId)`

Returns one available framework or conversation run. Framework results are limited to terminal runs that reached the best-effort projection. The workspace-scoped `run_id` is channel-neutral. Inspect `kind`, `channel`, and the `source_*` fields to decide whether to open conversation detail, call detail, or framework trajectory next. Returns `404` when the run does not exist in the workspace.

A conversation run resolves by `run_id` at any age, for this read and for the run-scoped operations below. A projected framework run is looked up among recent framework history, so an older framework run can return `404` even though it appears in an earlier list page.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Get a Framework Trajectory

SDK: `client.runs.trajectory(runId)`

Returns ordered structural steps for a framework run. Check `truncated` before treating the returned sequence as complete.

Returns `404` when the run does not exist and `409` when the run is a conversation run. Use conversation detail for per-turn conversation history.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/trajectory" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Takeover Eligibility

Every run carries a server-computed `takeover` object, `eligible`, `mode_options`, and `reason`, based on its channel and status, and `held_by` while an operator holds a text run. Clients should use it for those eligibility checks and also confirm that the selected voice runtime supports the requested control: offer voice takeover and guidance only when the run's `session_provider` is `concurrence`. A live realtime-provider call (`gpt_realtime`, `eleven_realtime`, `gpt_live`, or `grok_voice`) can be listed without supporting operator takeover or guidance. When `eligible` is false, `reason` is short text that explains why.

The voice eligibility object exposes `listen` and `takeover`, and execution requires a supported platform-managed voice session. Live non-voice runs (SMS, WhatsApp, email, web, and iMessage) expose `takeover` only. An operator drives those channels by staging authored turns rather than joining a live media stream. Framework and non-live runs are not eligible. `held_by` gives the holder's `operator_id`, `since`, and `expires_at`, the end of the hold unless it is renewed, and is absent while nobody holds the run. A held run stays `eligible`, and another operator's takeover on it is refused with `409`, so read `held_by` before you offer the control.

## Operator Takeover

{% hint style="warning" %}
**Beta.** Operators is a beta feature. A workspace must be enabled for it before it can call the run operations below or the [operator operations](https://docs.concurrence.com/developer-guide/platform-api/conversations/operators.md). Any other workspace gets `403` with the message `Operators is a beta feature that is not enabled for this workspace`. Ask your Concurrence representative to enable it.
{% endhint %}

For a custom operator interface, these API operations provide controls that require an authorized operator identity and a supported runtime. Use the **Live** status filter on the Console Runs page to find active runs. [Build Your Own Operator Console](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md) walks through building one.

An operator can take over a live run and hand it back by channel-neutral `run_id`. Voice takeover uses a live media session and supports listen or drive mode. Non-voice takeover holds the run for 90 seconds at a time: the run is `paused`, the agent does not reply apart from the emergency reply and the case where the platform cannot confirm the hold, both described in [While an Operator Holds a Run](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md#while-an-operator-holds-a-run), and the operator stages replies. The hold ends when the holder hands it back or stops renewing it.

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-dd1ea0f77455b505f8ae232dd3480d30656b7b0a%2Foperator-text-takeover-flow.svg?alt=media" alt="To take over a text run, list live runs and read each run&#x27;s takeover object, then take over, which holds the run for 90 seconds and pauses it. Renew the hold at least every 30 seconds while the operator is present. Stage one reply at a time and read its state: pending, consumed, or expired. A handback ends the hold and discards a pending reply. A hold that nobody renews ends by itself, and the agent answers the person&#x27;s next message."><figcaption><p>On a text run, taking over holds the run for 90 seconds. Renew the hold, stage one reply at a time, and read its state. A handback discards a pending reply.</p></figcaption></figure>

### Credentials <a href="#credentials" id="credentials"></a>

Taking over, renewing, handing back, staging a reply, switching mode, and sending guidance act as the signed-in operator. They need the operator's identity token and `Operator:Update`, which the operator, admin, and owner roles carry. The `operator_id` in the body must be the caller's own operator. Impersonation is rejected for every role. A workspace API key is refused with `403` and the message `Identity JWT required for this operation`. Listing, reading, and summarizing runs, and [reading a staged reply](#read-a-staged-reply), accept either credential. See [Sign the Operator In](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md#credentials).

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-cb38731d1663c5c54fedefb00448bb9a50859dfd%2Foperator-credentials-map.svg?alt=media" alt="A workspace API key can read runs, operators, and the queue but gets 403 on every operator action. The operator&#x27;s identity token can read and can also take over, renew the hold, hand back, switch mode, stage a reply, send guidance, join and leave a call, and record a wrap-up. The operator in the request must be the signed-in caller."><figcaption><p>A workspace API key cannot act on a live conversation. Only the signed-in operator's identity token can act, and only as that operator.</p></figcaption></figure>

### Take Over a Run

SDK: `client.runs.takeOver(runId, body)`

Registers the operator on a live run. In `takeover` mode the agent is suspended so the human drives. In `listen` mode the operator monitors without driving. Non-voice channels support `takeover` mode only. `mode` defaults to `takeover`, so pass `listen` explicitly to join a voice run silently first. A voice response carries `participant_call_sid`, which [Switch Mode](#switch-mode) requires.

On a text run, taking over holds the run. The run is `paused`, and the agent does not reply while the hold lasts, apart from the emergency reply and the case where the platform cannot confirm the hold, both described in [While an Operator Holds a Run](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md#while-an-operator-holds-a-run). The response carries `held_by` (`operator_id`, `since`, and `expires_at`), `hold_token`, and `lease_seconds`, which is 90. The hold ends at `expires_at` unless the holder renews it with [Renew a Hold](#renew-a-hold). The holder taking over again keeps the hold and its `since`, moves the end, and gets the same `hold_token`. The `hold_token` is opaque: send it back exactly as received.

Another operator's takeover on a held run returns `409` with `detail.code` `run_held`. `detail.held_by` gives the holder's `operator_id`, `since`, and `expires_at`, and `detail.operator_name` names them. Either can be null. A hold that has ended does not block a takeover. A takeover returns `503` with `Retry-After` when the run is busy.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/takeover" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Renew a Hold <a href="#renew-a-hold" id="renew-a-hold"></a>

SDK: `client.runs.renewTakeover(runId, body)`, in version 0.127.0 and later

Moves the end of the hold the caller took to 90 seconds from now. The body carries `operator_id` and the `hold_token` that the takeover returned, sent exactly as received: the match is exact, so a token that was parsed and written back with less precision names no hold. The response carries `run_id`, `held_by` with the new `expires_at`, and `lease_seconds`.

```json
{ "operator_id": "<operator id>", "hold_token": "<hold_token from the takeover>" }
```

A renewal only extends the hold it names. After a handback, after the hold ended, or after another operator took the run, it returns `409` with `detail.code` `hold_lost`, and the run stays as it is. It does not take a run, so taking over again is the only way to hold a run again. Renew at least every 30 seconds while the operator is present, so one failed renewal does not end the hold. A renewal that succeeds is not written to the audit log. One refused with `hold_lost` is, as `operator.takeover_renewed` with a `result` of `failed`. It returns `503` with `Retry-After` when the run is busy.

Renewing needs `Operator:Update`, the operator's identity token, and the caller's own `operator_id`, like takeover.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/takeover/renew" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Hand a Run Back

SDK: `client.runs.handBack(runId, body)`

Releases the operator from the run. On a text run, the hold ends and the agent answers again. Only the operator who holds the run, or a caller with `Operator:Delete` (the `admin` and `owner` roles) acting as their own operator, can hand back a held run. Anyone else gets `403` and the hold stays. Any operator can hand back a hold that has ended, and a handback on a run nobody holds succeeds and changes nothing. A handback discards a reply that is still waiting to be sent, and its state then reads `expired`. A message the person sent during the hold is not answered by the handback: the agent answers the person's next message, with the held messages in context. It returns `503` with `Retry-After` when the run is busy. For voice, the operator leaves the live media session and the agent is resumed. Subsequent behavior uses whatever conversation state and takeover evidence the runtime successfully retained. The handback response does not guarantee a complete transcript of operator activity.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/handback" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Author a Non-Voice Turn

SDK: `client.runs.authorTurn(runId, body)`, in version 0.116.0 and later

Stages the next operator-authored reply on a held SMS, WhatsApp, email, web, or iMessage run. The reply is 1 to 4,000 characters. The caller needs a live hold on the run: without one the call returns `409` with `detail.code` `no_hold`. The platform hands the reply to the agent before the call returns, and the agent sends it as its own message in the conversation, only while the operator who staged it still holds the run. A `200` means the reply was handed over, not that it was sent. It carries `staged`, `reply_id`, `expires_at`, and `waits_for_person`. A run has one reply waiting at a time: staging another returns `409` with `detail.code` `reply_pending` and the waiting `reply_id`. A reply waits up to 2 minutes, and a handback discards it. Read what became of it with [Read a Staged Reply](#read-a-staged-reply).

On a web conversation that an external user session owns, no agent runs for the person. The response has `waits_for_person` set to true, and the reply is sent when the person next sends a message or polls, before it expires. It then appears in the conversation's turns. The response to that message or poll does not carry it.

A reply that cannot be handed to the agent is discarded, so its state reads `expired`, and `detail.code` says why. A `409` with `conversation_not_active`, `reply_expired`, `channel_routing_unavailable` (the person has not written recently enough for the platform to reach them on this channel), or `reply_not_deliverable` means the reply was not sent. A `502` or `503` with `agent_unreachable` means the reply was not sent and sending it again is safe. A `502` with `agent_rejected_request` means the platform's request to send the reply was refused: the reply was not sent, and sending it again will not help. A `502` with `conversation_read_failed` means nothing was staged or sent, and sending it again is safe. A `502` with `delivery_unconfirmed` means the reply may have been sent, so check the conversation before you send it again. The call returns `503` with `Retry-After` when the run is busy.

Voice runs return `409` because the operator drives them through live audio.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/authored-turn" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Read a Staged Reply <a href="#read-a-staged-reply" id="read-a-staged-reply"></a>

SDK: `client.runs.getAuthoredTurn(runId)`, in version 0.127.0 and later

Reads what became of the last reply staged on a non-voice run. `state` is one of:

* `none`: no reply is on record for the run.
* `pending`: the reply waits to be sent.
* `consumed`: the platform took the reply to send it. This does not confirm that the channel delivered it.
* `expired`: the reply ran out of time, or a handback discarded it.

Once a reply was staged, the response also carries `reply_id`, `operator_id`, `staged_at`, and `expires_at`. A reply waits up to 2 minutes.

```json
{ "run_id": "<run id>", "state": "pending", "reply_id": "<reply id>", "operator_id": "<operator id>", "staged_at": "<timestamp>", "expires_at": "<timestamp>" }
```

Reading needs `Operator:View`, which the viewer, operator, member, admin, and owner roles carry, so a workspace API key can read it.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/authored-turn" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Switch Mode

SDK: `client.runs.switchMode(runId, body)`

Toggles an operator who has already joined a voice run between `listen` and `takeover`. The request carries the `participant_call_sid` from the takeover response. Non-voice runs return `409` because they support authored-turn takeover only.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/switch-mode" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Operator Audio

Operators join supported voice calls by phone through the [operator join workflow](https://docs.concurrence.com/developer-guide/platform-api/conversations/operators.md), not through browser audio. Use run takeover and mode-switch controls for the corresponding operator state changes.

### Send Guidance

SDK: `client.runs.sendGuidance(runId, body)`

Sends text guidance to a live voice run. Guidance is delivered as a prioritized instructional event that can interrupt current agent speech, unlike a factual [external event](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md), which queues behind current speech. The returned delivery status does not guarantee exact response timing or that the model follows the instruction verbatim. Non-voice channels return `409`. Use authored-turn takeover when an operator must send a reply.

The audit record captures the run, channel, operator identity, and a content fingerprint, never the raw guidance text. The response `status` is `delivered`, `queued_no_subscriber`, `deduplicated`, `failed`, or `unknown`. See [Operator Guidance](https://docs.concurrence.com/developer-guide/platform-api/conversations/operators.md#operator-guidance).

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/runs/{run\_id}/guidance" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Agent Forge CLI

Agent Forge `v0.1.44+` exposes the unified read surface:

```bash
forge platform run list \
  --kind conversation \
  --channel voice \
  --status live \
  --limit 50 \
  --env <env>

forge platform run summary --kind conversation --env <env>
forge platform run get <run_id> --env <env>
```

Add `--json` for the raw response. The CLI accepts one value per filter flag and prints `--continuation-token` when another page is available. Pass that token unchanged to the next `run list` call. The REST API itself supports repeated filter values.

## Rate Limits

Each list, summary, detail, trajectory, and staged-reply read allows 60 requests per minute. Each takeover, renew, handback, authored-turn, mode-switch, and guidance operation allows 10 requests per minute. Renewing a hold every 30 seconds uses 2 of the 10 requests a minute that the renew operation allows. Limits are enforced per authenticated credential, run, and operation. The list and summary reads cover the workspace rather than one run, so they are enforced per authenticated credential and operation. Successful limit checks return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` response also returns `Retry-After`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
