> ## Documentation Index > Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Batch Runs > Returns a paginated list of batch runs for the specified agent, sorted by most recently created first. Use page and size to navigate through results. ## OpenAPI ````yaml get /v1/batch-runs openapi: 3.0.1 info: title: SigmaMind APIs description: OpenAPI documentation SigmaMind Agent Builder APIs version: '1.0' servers: - url: https://api.sigmamind.ai description: SigmaMind AI Agent Builder APIs security: - apiKeyAuth: [] tags: - name: Chats description: >- Endpoints for creating and managing text-based chat sessions with an agent. A session is started by specifying an agent and an opening message. Returns a chatId used in all subsequent get, update, completion, and end-session calls. - name: Calls description: >- Endpoints for creating and managing outbound phone calls. A call is initiated by specifying an agent, caller number, and destination number — dynamic variables can be included to personalise the agent's behaviour. Returns a callId used in all subsequent get and delete operations. - name: Phone Numbers description: >- Endpoints for managing phone numbers used in outbound and inbound calls. Supports purchasing a new number through SigmaMind or importing an existing number via SIP trunking (BYO). Each number can be assigned separate inbound and outbound agents. - name: Campaigns description: >- Endpoints for creating and managing outbound call campaigns. A campaign dials a CSV-uploaded contact list using a selected agent and caller number, with support for immediate or scheduled launch. Returns a campaignId used in all subsequent get, update, and delete operations. - name: Agents description: >- Endpoints for creating and managing single prompt agents. An agent is configured with a system prompt, voice settings, and optional tools. Returns an agentId used in all subsequent update, call, and simulation operations. - name: Integrations description: >- Endpoints for creating and managing third-party integrations (e.g. Shopify, Cal.com). An integration links your account to an external service and acts as the parent resource for auth credentials and API tools. Returns an integrationId used in all subsequent auth and tool operations. - name: Integration Auth description: >- Endpoints for managing authentication credentials for a third-party integration. Supports API Key, Basic, and Bearer token credential types — scoped to an integration and injected automatically by tools when executing. Returns an authId used in all subsequent get, update, and delete operations. - name: Integration Tools description: >- Endpoints for creating and managing API tools backed by a third-party integration. Each tool defines an HTTP endpoint, method, and parameter schema — scoped to an integration and using its stored auth credentials when executing. Returns a toolId used in all subsequent get, update, delete, and execute operations. - name: Webhooks description: >- Endpoints for registering and managing webhooks. A webhook delivers real-time event notifications via HTTP POST when selected events occur on a specific agent — each webhook is scoped to one agent and one or more event types. Payloads are signed with an HMAC secret — verify the signature on your server to confirm authenticity. - name: Test Cases description: >- Endpoints for creating and managing simulation test cases for an agent. A test case defines a conversation scenario — including user persona, goals, and expected behaviour — used to generate a synthetic conversation with the agent. Returns a testCaseId used in all subsequent get, update, delete, and batch-run operations. - name: Batch Runs description: >- Endpoints for creating and managing batch runs of simulation test cases. A batch run executes multiple test cases in parallel against a selected agent and aggregates the results for review. Returns a batchId used in all subsequent get and list test-run operations. - name: Test Runs description: >- Endpoints for retrieving test run results within a batch. Each test run represents a single test case execution within a batch run, identified by a jobId. Use batchId and agentId to scope results to the correct batch. - name: API Keys description: >- Endpoints for creating and managing API keys used to authenticate public API requests. Each key must be included in the X-API-Key request header. Returns a keyId used in all subsequent get, revoke, and delete operations. - name: QA Rules description: >- Endpoints for creating and managing quality assurance rules applied to agent conversations. A QA rule defines evaluation criteria used to automatically assess conversation quality. Returns a qaRuleId used in all subsequent get, update, and delete operations. - name: QA Issues description: >- Endpoints for retrieving and managing quality assurance issues flagged across agent conversations. A QA issue is created with status 'Fail' when a conversation violates one or more QA rules — capturing the offending rule reference. It is created with status 'Success' when the conversation passes the evaluation criteria of QA rule(s). Returns a qaIssueId used in all subsequent get operations. paths: /v1/batch-runs: get: tags: - Batch Runs summary: List Batch Runs description: >- Returns a paginated list of batch runs for the specified agent, sorted by most recently created first. Use page and size to navigate through results. operationId: listBatches parameters: - name: agentId in: query description: Unique identifier of the agent whose batch runs are to be listed. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd - name: page in: query description: >- Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: >- Number of batch runs to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseBatchResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/batch-runs status: 400 timestamp: '2026-05-05T10:06:43.879Z' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/batch-runs status: 401 timestamp: '2026-05-05T10:06:43.879Z' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/batch-runs status: 403 timestamp: '2026-05-05T10:06:43.879Z' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/batch-runs status: 404 timestamp: '2026-05-05T10:06:43.879Z' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/batch-runs status: 500 timestamp: '2026-05-05T10:06:43.880Z' components: schemas: PaginatedResponseBatchResponse: type: object properties: data: type: array description: >- List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/BatchResponse' page: type: integer description: >- Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: >- Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: >- Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: >- Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: >- Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: >- Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: >- Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. Error: type: object properties: timestamp: type: string description: Error timestamp in ISO format format: date-time status: type: integer description: HTTP status code example: 400 error: type: string description: Error type or HTTP status message example: Bad Request message: type: string description: Detailed error message example: Email is required path: type: string description: Request path where error occurred example: /v1/users validationErrors: type: object description: Field validation errors (if any) example: |- { "email": "Email is required", "name": "Name is too short" } description: Standard error response BatchResponse: type: object properties: batchId: type: string description: The unique identifier of the batch run. example: batch_s0OJu2JWR8R45Fai workspaceId: type: string description: >- The unique identifier of the workspace under which the batch run was created. example: org_V6eZ2zg8ziDx5pft agent: $ref: '#/components/schemas/AgentResponse' createdDate: type: string description: The UTC timestamp indicating when the batch run was created. format: date-time example: '2026-03-26T10:52:45.565Z' testCases: type: array description: >- The list of test cases included in this batch run, along with their individual simulation results. items: $ref: '#/components/schemas/TestCaseResponse' successfulAttempts: type: integer description: >- The total number of simulation attempts across all test cases in this batch run that were evaluated as successful. format: int64 example: 4 failedAttempts: type: integer description: >- The total number of simulation attempts across all test cases in this batch run that were evaluated as failed. format: int64 example: 1 totalAttempts: type: integer description: >- The total number of simulation attempts executed across all test cases in this batch run. format: int64 example: 5 description: >- List of items for the current page. Contains up to 'size' number of records. AgentResponse: type: object properties: name: type: string description: The display name of the assigned agent. example: New AI Agent agentId: type: string description: The unique identifier of the agent within the system. example: agent_D5D0p7TUs66TTAEAx status: type: string description: The current operational status of the agent. example: Live enum: - Live - Testing - Disabled description: >- Agent assigned to handle all calls in this campaign. Contains the agent's ID, name, and current status. All contacts in the campaign's contact list will be called using this agent. TestCaseResponse: type: object properties: testCaseId: type: string description: The unique identifier of the test case. example: tc_d17T6uReChpyfFeP label: type: string description: >- A human-readable name or label for the test case, used to identify it in reports and dashboards. example: Angry Customer - Cancellation Flow agent: $ref: '#/components/schemas/AgentResponse' workspaceId: type: string description: >- The unique identifier of the workspace under which this test case was created. example: org_V6eZ2zg8ziDx5pft llmModel: type: string description: >- The LLM model used to generate Agent responses during the simulation. example: gpt-4o-mini mockData: type: array description: >- The list of mock variables and their simulated values that were used to substitute for real external data sources during the simulation. example: - variableName: customer_name value: John Doe - variableName: account_status value: active items: $ref: '#/components/schemas/MockDataResponse' userPrompt: type: string description: >- The prompt that defined the persona and intent of the simulated user, driving the user-side messages throughout the conversation. example: You are an angry customer who wants to cancel your subscription. attempt: type: integer description: >- The number of times this test case was configured to run as independent simulation attempts. format: int64 example: 5 successCriteria: type: string description: >- The plain-language description of what a successful agent response looks like, used to evaluate the agent's performance after each simulation run. example: >- The agent should acknowledge the cancellation request, present retention alternatives, and confirm the cancellation if the customer insists. MockDataResponse: type: object properties: variableName: type: string description: >- The name of the variable that was substituted with mock data during the simulation. example: user_name value: type: string description: >- The simulated value that was assigned to the variable for the duration of the test run. example: John Doe description: >- The list of mock variables and their simulated values that were used to substitute for real external data sources during the simulation. example: - variableName: customer_name value: John Doe - variableName: account_status value: active securitySchemes: apiKeyAuth: type: apiKey description: >- Authenticate every request by passing your API key in the `X-API-Key` header. To get your key, go to Dashboard → API Keys and create or copy your Production API key. name: X-API-Key in: header ````