> ## Documentation Index > Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List batches > List the call batches of your account, newest first. Every batch appears here, including calls placed from the dashboard; single calls also get a batch. Returns 20 batches per page. ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/v1/outbound/batches openapi: 3.1.0 info: title: Customer API version: 1.0.0-beta description: > **Beta.** This API is in beta. Contracts can still change while we complete it, including breaking changes; we announce changes in the release notes and keep them as rare as we can. Pin your integration to the field names and status codes documented here and treat unknown fields as optional. REST API to create and configure voice agents, add tools, test them with evals, read conversations, and place AI outbound calls. **Authentication.** Voice agents, settings, tools, evals and conversations use an API token created on the **Keys** page of your dashboard. Each operation lists the scope it needs under `x-required-scopes`; `:*` grants every action of a resource. Outbound calls use a separate outbound API token from the **Outbound Calls** page. Send either token as `Authorization: Bearer `. **Responses.** A single resource is returned as a flat JSON object; a collection is wrapped in a plural key (`voice_agents`, `tools`, `evals`, `conversations`) next to its paging fields. Deleting returns `204 No Content`. Everything is addressed by the voice agent's `id`; prompts and numbers are internal. **Errors.** Authentication failures return `{ "error", "message" }`. Request quotas return `429` with a `Retry-After` header and `{ "error", "message", "details" }`, where `error` is a stable machine-readable code. Every API call must finish within 30 seconds; longer requests return `503` with `mf-core:api-request-timeout`. Validation errors list the problems per field; the exact shape is shown on each operation. servers: - url: https://app.miyon.ai security: [] tags: - name: Voice Agents description: >- Create and manage voice agents. Configure them through the voice, prompt and knowledge-base settings endpoints. - name: Voice Agent Settings description: >- Read and change a voice agent's voice, prompt and knowledge-base settings. A voice agent has one prompt (its instructions, greeting and conversation settings). Read the schema of a settings group, then update one `key`/`value` pair per request. - name: Tools description: >- Create, configure, enable and execute agent tools. Tools are enabled per voice agent with `agent_id`. These endpoints accept scoped API tokens only; every error uses the `{ "error", "message", "details" }` envelope with a stable `mf-core:tool-*` code. - name: Outbound Calls description: >- Place AI calls and review their outcome. Authenticate with the outbound API token from the **Outbound Calls** page. - name: Conversations description: >- List and inspect the conversations of your account, including transcripts when your retention settings allow. - name: Evals description: >- Evals are automated test conversations that check how a voice agent responds. A scenario contains cases; each case contains the caller's turns and what the agent must say or do. Run a scenario to get pass/fail results. paths: /api/v1/outbound/batches: get: tags: - Outbound Calls summary: List batches description: > List the call batches of your account, newest first. Every batch appears here, including calls placed from the dashboard; single calls also get a batch. Returns 20 batches per page. operationId: listBatches parameters: - name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Page number, starting at 1. 20 batches per page. responses: '200': description: A page of batches. content: application/json: schema: type: object properties: success: type: boolean examples: - true description: Always true. batches: type: array items: type: object properties: batch_id: type: string format: uuid description: >- ID of the batch. Use it with `GET /api/v1/outbound/batches/{id}`. batch_created_at: type: string format: date-time description: When the batch was created. agent_name: type: - string - 'null' description: >- Name of the agent that placed the calls, if it still exists. agent_number: type: string description: Number or SIP ID of the agent. phone_count: type: integer description: Numbers in this batch. called_count: type: integer description: Numbers that were actually dialed. approved_count: type: integer description: >- Calls approved for dialing. Equals `phone_count` for API batches; for SMS-confirmed dashboard batches, the recipients who agreed. pending_count: type: integer description: >- Recipients who have not yet answered the SMS confirmation (dashboard batches only). rejected_count: type: integer description: >- Recipients who declined by SMS (dashboard batches only). expired_count: type: integer description: >- SMS confirmations that expired (dashboard batches only). cancelled_count: type: integer description: Call records canceled before dialing. mode: type: string enum: - direct - sms description: >- `direct` for calls placed through this API, `sms` for dashboard batches confirmed by SMS first. description: The page of batches, newest first. total_pages: type: integer examples: - 3 description: Number of pages. current_page: type: integer examples: - 1 description: Page returned. total_entries: type: integer examples: - 42 description: Total batches of your account. '401': $ref: '#/components/responses/OutboundUnauthorized' '403': $ref: '#/components/responses/OutboundForbidden' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' security: - scopedJwt: [] - outboundBearer: [] components: responses: OutboundUnauthorized: description: >- Missing or invalid API token. Outbound-token failures use the `success`/`error` shape; scoped-token failures (expired, revoked, IP not allowed) use the `error`/`message` shape. content: application/json: schema: anyOf: - $ref: '#/components/schemas/OutboundError' - $ref: '#/components/schemas/AuthError' examples: missing: value: success: false error: Missing authorization token invalid: value: success: false error: Invalid authorization token scopedExpired: value: error: Authentication failed message: Token expired OutboundForbidden: description: >- Outbound calling is switched off for your account, or the scoped token lacks the required outbound scope. Contact support for the first case. content: application/json: schema: anyOf: - $ref: '#/components/schemas/OutboundError' - $ref: '#/components/schemas/AuthError' examples: disabled: value: success: false error: Outbound calls are currently disabled missingScope: value: error: Forbidden message: 'Missing required scope: outbound:write' RateLimited: description: >- Too many requests. Wait the number of seconds given in `Retry-After` before retrying. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: mf-core:rate-limit-exceeded message: Rate limit exceeded details: policy: api_write retry_after: 3 ServiceUnavailable: description: >- The request was not completed. Either it exceeded the 30-second request time limit that applies to every API call (narrow the request and retry), or rate limiting is temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: timeout: value: error: mf-core:api-request-timeout message: The API request exceeded the 30-second time limit details: {} limiter: value: error: mf-core:rate-limiter-unavailable message: API rate limiting is temporarily unavailable details: policy: api_write schemas: OutboundError: type: object required: - success - error properties: success: type: boolean const: false description: Always false. error: type: string description: Description of the issue, in English. error_type: type: string description: >- Stable machine-readable cause. Present on limit rejections and on classified placement failures, omitted otherwise. enum: - outbound_burst_limited - outbound_limit_request_exceeded - outbound_temporarily_unavailable - rate_limit - destination_not_permitted - caller_id_not_allowed - placement_failed detail: type: string description: Where to go next. Only present on the `rate_limit` variant of 429. AuthError: type: object description: >- Returned when the API token is missing, invalid, expired or lacks the required scope. properties: error: type: string description: Short error category. examples: - Authentication failed - Forbidden message: type: string description: Human-readable explanation. Absent on some 403 responses. examples: - 'Missing required scope: voice_agents:write' required: - error ApiError: type: object description: >- Error format with a stable machine-readable `error` code, a human-readable `message` and request-specific `details`. properties: error: type: string description: >- Stable machine-readable error code, for example `mf-core:rate-limit-exceeded`. message: type: string description: Human-readable explanation. details: type: object additionalProperties: true description: >- Request-specific data, for example the offending parameter or the quota policy. required: - error - message - details securitySchemes: scopedJwt: type: http scheme: bearer bearerFormat: JWT description: >- Scoped API token. Required scopes are listed on each operation in x-required-scopes. outboundBearer: type: http scheme: bearer description: > Outbound token from the **Outbound Calls** page. It can no longer be created or rotated; existing tokens keep working with full outbound access. For new integrations, create a scoped API token on the **Keys** page with the Outbound scope (`outbound:read` for read-only, `outbound:*` for full access) and send it as `scopedJwt`. The deprecated `/api/v1/outbound_calls` operations accept only this token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.