> ## Documentation Index > Fetch the complete documentation index at: https://docs.believe.app/llms.txt > Use this file to discover all available pages before exploring further. # Get Batch Status > This endpoint retrieves the current status and details of a flywheel batch by its ID. ## Overview The Get Batch Status endpoint allows you to retrieve detailed information about a flywheel batch, including its current status, execution results, and pipeline details. This is useful for monitoring the progress of batch operations and checking execution results. ## Authentication This endpoint requires API key authentication. The API key must have either `burn` or `airdrop` scopes. To authenticate, provide your API key in the `x-believe-api-key` request header. Example: ``` x-believe-api-key: your_actual_api_key_here ``` ## Rate Limiting Requests to this endpoint are rate-limited to 10 requests per second per API key. ## Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------- | | `batchId` | string | Yes | The UUID of the batch to retrieve status for. | ### Example Request ``` GET /flywheel/batch/550e8400-e29b-41d4-a716-446655440000 ``` ## Response Body On success, the API returns a JSON object containing the complete batch information: | Field | Type | Description | | --------------- | ------ | --------------------------------------------------------- | | `id` | string | The unique batch identifier (UUID). | | `flywheelId` | string | The flywheel this batch belongs to. | | `tokenId` | string | The token ID associated with this batch. | | `mintAddress` | string | The Solana mint address for the token. | | `status` | string | Current batch status (see status values below). | | `batchIndex` | string | The multisig batch index used for execution. | | `vaultIndex` | string | The vault index within the multisig. | | `multisig` | string | The multisig wallet address. | | `vaultAddress` | string | The vault address for token operations. | | `initResult` | Object | (Optional) Results from the batch initialization process. | | `executeResult` | Object | (Optional) Results from the batch execution process. | | `dateCreated` | string | ISO 8601 timestamp when the batch was created. | | `dateUpdated` | string | ISO 8601 timestamp when the batch was last updated. | ### Batch Status Values | Status | Description | | -------------------- | ------------------------------------------------------------- | | `AVAILABLE_TO_QUEUE` | Batch has been created but not yet finalized for execution. | | `FINALIZED` | Batch has been finalized and is ready for execution approval. | | `EXECUTED` | Batch has been successfully executed. | | `FAILED` | Batch execution failed. | ### Init Result Object (Optional) Present when status is `FINALIZED` or later. | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------- | | `total` | number | Total number of setup transactions processed. | | `totalSuccessful` | number | Number of setup transactions that succeeded. | | `totalFailed` | number | Number of setup transactions that failed. | | `successfulExecutions` | Array | Array of successful bundle executions during setup. | | `failedTxMsg` | string | (Optional) Error message if setup failed. | | `batchIndex` | number | The batch index used in the multisig. | ### Execute Result Object (Optional) Present when status is `EXECUTED` or `FAILED`. | Field | Type | Description | | ----------------------------- | ------ | ----------------------------------------------------------- | | `total` | number | Total number of pipeline transactions. | | `totalSuccessful` | number | Number of pipeline transactions that executed successfully. | | `totalFailed` | number | Number of pipeline transactions that failed. | | `successfulExecutions` | Array | Array of successful bundle executions. | | `failedOnTransactionIndex` | number | (Optional) Transaction index where failure occurred. | | `failedStartTransactionIndex` | number | (Optional) Starting index of the failed transaction batch. | | `failedTxMsg` | string | (Optional) Error message describing the failure. | ### Example Response (Finalized Batch) ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "flywheelId": "flywheel_abc123", "tokenId": "token_def456", "mintAddress": "So11111111111111111111111111111111111111112", "status": "FINALIZED", "batchIndex": "42", "vaultIndex": "0", "multisig": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "vaultAddress": "HF8dF3nXy48op4dgdNPc86vqG79JTta7wvEbAWW8NXKv", "initResult": { "total": 3, "totalSuccessful": 3, "totalFailed": 0, "successfulExecutions": [ { "bundleId": "a1b2c3d4e5f6789012345678901234567890abcdef", "txHashes": ["3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1KqJ8LoX2GbM4aC9eR", "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC"] } ], "batchIndex": 42 }, "dateCreated": "2025-01-27T12:00:00.000Z", "dateUpdated": "2025-01-27T12:05:00.000Z" } ``` ### Example Response (Executed Batch) ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "flywheelId": "flywheel_abc123", "tokenId": "token_def456", "mintAddress": "So11111111111111111111111111111111111111112", "status": "EXECUTED", "batchIndex": "42", "vaultIndex": "0", "multisig": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "vaultAddress": "HF8dF3nXy48op4dgdNPc86vqG79JTta7wvEbAWW8NXKv", "initResult": { "total": 3, "totalSuccessful": 3, "totalFailed": 0, "successfulExecutions": [ { "bundleId": "a1b2c3d4e5f6789012345678901234567890abcdef", "txHashes": ["3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1KqJ8LoX2GbM4aC9eR", "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC"] } ], "batchIndex": 42 }, "executeResult": { "total": 8, "totalSuccessful": 8, "totalFailed": 0, "successfulExecutions": [ { "bundleId": "d0f38d76f53a94b1fa1a0e2c6be123da7ce634afa87733939e406d39f659e68e", "txHashes": [ "27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh", "4KkFDQ1MBKHrvsNjbNWDttNdHq4f6bys7T5GUDc7Vb6Uv1hUGDVhHCQamnQFmFjnDTQxga6KMi9Yx6fru2sMucKa", "4E6vzH1ep75ArgxFpoXqWgkPinnuFq4kKp2EMnpjcDXKeW5PSfdqQeSusPaxHjf9qfk9ZGcoZkjvY2SzovGdd3Kf", "4pCsbF58DHVfpUZdzmBKimLrAPNE75cXf82FejmYvvxe2eUEXhBhV4RFV9btayMrLsA8QUY8ABed4MxXDUpoB9L3" ] } ] }, "dateCreated": "2025-01-27T12:00:00.000Z", "dateUpdated": "2025-01-27T12:10:00.000Z" } ``` ## Use Cases 1. **Monitor Batch Progress**: Check if a batch has moved from `FINALIZED` to `EXECUTED` status. 2. **Retrieve Execution Results**: Get detailed transaction hashes and bundle IDs after execution. 3. **Debug Failed Batches**: Examine error messages and failure details when status is `FAILED`. 4. **Audit Trail**: Review the complete lifecycle of a batch operation with timestamps. 5. **Integration Status Checks**: Poll this endpoint to determine when to proceed with next steps in your application flow. ## Error Codes The batch status endpoint can return specific error codes. | Error Code | Status | Description | | --------------------- | ------ | ------------------------------------------- | | `ERR_BATCH_NOT_FOUND` | 404 | No batch exists with the provided batch ID. | ### Example Error Response ```json theme={null} { "error": "ERR_BATCH_NOT_FOUND", "message": "Batch not found" } ``` ## Integration Tips * **Polling Strategy**: Use this endpoint to poll for status changes after calling batch init or execute. * **Error Handling**: Check both the HTTP status and the batch status field for complete error information. * **Transaction Verification**: Use the returned transaction hashes to verify operations on Solana explorers. * **Status Transitions**: Batches typically progress: `AVAILABLE_TO_QUEUE` → `FINALIZED` → `EXECUTED`/`FAILED`. ## OpenAPI ````yaml GET /v1/flywheel/batch/{batchId} openapi: 3.1.0 info: title: OpenAPI Plant Store description: >- A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification license: name: MIT version: 1.0.0 servers: - url: https://public.believe.app security: - bearerAuth: [] paths: /v1/flywheel/batch/{batchId}: get: tags: - Flywheel summary: Get Batch Status description: >- This endpoint retrieves the current status and details of a flywheel batch by its ID. parameters: - name: batchId in: path description: The UUID of the batch to retrieve status for. required: true schema: type: string format: uuid responses: '200': description: Successful batch status retrieval. content: application/json: schema: $ref: '#/components/schemas/BatchStatusResponse' '401': description: Unauthorized - API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found - Batch not found. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKeyAuth: [] components: schemas: BatchStatusResponse: type: object required: - id - flywheelId - tokenId - mintAddress - status - batchIndex - vaultIndex - multisig - vaultAddress - dateCreated - dateUpdated properties: id: type: string description: The unique batch identifier (UUID). flywheelId: type: string description: The flywheel this batch belongs to. tokenId: type: string description: The token ID associated with this batch. mintAddress: type: string description: The Solana mint address for the token. status: type: string enum: - AVAILABLE_TO_QUEUE - FINALIZED - EXECUTED - FAILED description: Current batch status. batchIndex: type: string description: The multisig batch index used for execution. vaultIndex: type: string description: The vault index within the multisig. multisig: type: string description: The multisig wallet address. vaultAddress: type: string description: The vault address for token operations. initResult: $ref: '#/components/schemas/InitResult' description: Results from the batch initialization process (optional). executeResult: $ref: '#/components/schemas/ExecutionResult' description: Results from the batch execution process (optional). dateCreated: type: string format: date-time description: ISO 8601 timestamp when the batch was created. dateUpdated: type: string format: date-time description: ISO 8601 timestamp when the batch was last updated. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string InitResult: type: object required: - total - totalSuccessful - totalFailed - successfulExecutions - batchIndex properties: total: type: number description: Total number of setup transactions processed. totalSuccessful: type: number description: Number of setup transactions that succeeded. totalFailed: type: number description: Number of setup transactions that failed. successfulExecutions: type: array description: Array of successful bundle executions during setup. items: $ref: '#/components/schemas/SuccessfulExecution' failedTxMsg: type: string description: Error message if setup failed (optional). batchIndex: type: number description: The batch index used in the multisig. ExecutionResult: type: object required: - total - totalSuccessful - totalFailed - successfulExecutions properties: total: type: number description: Total number of pipeline transactions in the batch. totalSuccessful: type: number description: Number of pipeline transactions that executed successfully. totalFailed: type: number description: Number of pipeline transactions that failed to execute. successfulExecutions: type: array description: Array of successful bundle executions with their details. items: $ref: '#/components/schemas/SuccessfulExecution' failedOnTransactionIndex: type: number description: Transaction index where failure occurred (optional). failedStartTransactionIndex: type: number description: Starting transaction index of the failed batch (optional). failedTxMsg: type: string description: Error message describing the failure (optional). SuccessfulExecution: type: object required: - bundleId - txHashes properties: bundleId: type: string description: Jito bundle ID (hex string) for this group of transactions. txHashes: type: array description: >- Array of Solana transaction signatures (base58 strings) for executed transactions. items: type: string securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-believe-api-key ````