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

# List agent calls

> MCP reference for list_agent_calls.

Tool: `list_agent_calls`. Requires **Viewer or higher** in the applicable workspace and a connected [OAuth session](https://docs.agents.labs.bandwidth.com/mcp/authentication.md).

Use an agent ID from `list_agents`. Filter channel, lifecycle state, exact outcome code, and inclusive ISO 8601 dates. Timestamps without offsets use UTC. Results are newest first, with run-ID tie breaking.

Follow `next_page` until null, keeping filters and the returned `end_date` unchanged. If omitted, end date defaults to request time. `total` counts all matching calls. Pages are live reads, so existing outcomes can change. Null duration/cost means missing information, not zero; completion is not proof of business success.

## Arguments

| Name | Type | Required | Defaults and limits |
| - | - | - | - |
| `channel` | string or null | No | Default: `null` |
| `end_date` | string or null | No | Default: `null` |
| `outcome` | string or null | No | Default: `null` |
| `page` | integer | No | Default: `1`; minimum: `1` |
| `page_size` | integer | No | Default: `25`; minimum: `1`; maximum: `100` |
| `start_date` | string or null | No | Default: `null` |
| `state` | string or null | No | Default: `null` |
| `workflow_id` | integer | Yes | exclusiveMinimum: `0` |

## Example arguments

Replace sample resource IDs with IDs returned in your selected workspace.

```json theme={null}
{
  "workflow_id": 42,
  "page": 1,
  "page_size": 25
}
```

## Result and errors

The schema below describes MCP `structuredContent`, including the `result` wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See [troubleshooting](https://docs.agents.labs.bandwidth.com/mcp/troubleshooting.md).

**Effect:** Reads data. **Retry:** Declared idempotent. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "channel": {
>       "anyOf": [
>         {
>           "enum": [
>             "phone",
>             "web",
>             "chat"
>           ],
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "end_date": {
>       "anyOf": [
>         {
>           "format": "date-time",
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "outcome": {
>       "anyOf": [
>         {
>           "maxLength": 150,
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "page": {
>       "default": 1,
>       "minimum": 1,
>       "type": "integer"
>     },
>     "page_size": {
>       "default": 25,
>       "maximum": 100,
>       "minimum": 1,
>       "type": "integer"
>     },
>     "start_date": {
>       "anyOf": [
>         {
>           "format": "date-time",
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "state": {
>       "anyOf": [
>         {
>           "enum": [
>             "initialized",
>             "running",
>             "completed"
>           ],
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "workflow_id": {
>       "exclusiveMinimum": 0,
>       "type": "integer"
>     }
>   },
>   "required": [
>     "workflow_id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] Result schema
>
> ```json theme={null}
> {
>   "properties": {
>     "end_date": {
>       "format": "date-time",
>       "type": "string"
>     },
>     "next_page": {
>       "anyOf": [
>         {
>           "type": "integer"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     },
>     "organization_id": {
>       "type": "integer"
>     },
>     "page": {
>       "type": "integer"
>     },
>     "page_size": {
>       "type": "integer"
>     },
>     "records": {
>       "items": {
>         "properties": {
>           "agent_name": {
>             "type": "string"
>           },
>           "campaign_id": {
>             "anyOf": [
>               {
>                 "type": "integer"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "channel": {
>             "enum": [
>               "phone",
>               "web",
>               "chat"
>             ],
>             "type": "string"
>           },
>           "cost_usd": {
>             "anyOf": [
>               {
>                 "type": "number"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "created_at": {
>             "format": "date-time",
>             "type": "string"
>           },
>           "direction": {
>             "anyOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "duration_seconds": {
>             "anyOf": [
>               {
>                 "type": "number"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "end_reason": {
>             "anyOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "outcome": {
>             "anyOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "outcome_status": {
>             "enum": [
>               "recorded",
>               "not_recorded"
>             ],
>             "type": "string"
>           },
>           "run_id": {
>             "type": "integer"
>           },
>           "state": {
>             "type": "string"
>           },
>           "version": {
>             "anyOf": [
>               {
>                 "type": "integer"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "workflow_id": {
>             "type": "integer"
>           }
>         },
>         "required": [
>           "run_id",
>           "workflow_id",
>           "agent_name",
>           "created_at",
>           "channel",
>           "direction",
>           "state",
>           "outcome",
>           "outcome_status",
>           "end_reason",
>           "duration_seconds",
>           "cost_usd",
>           "version",
>           "campaign_id"
>         ],
>         "type": "object"
>       },
>       "type": "array"
>     },
>     "start_date": {
>       "anyOf": [
>         {
>           "format": "date-time",
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     },
>     "total": {
>       "type": "integer"
>     },
>     "workflow_id": {
>       "type": "integer"
>     }
>   },
>   "required": [
>     "organization_id",
>     "workflow_id",
>     "records",
>     "total",
>     "page",
>     "page_size",
>     "next_page",
>     "start_date",
>     "end_date"
>   ],
>   "type": "object"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.