​
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

ParameterTypeRequiredDescription
batchIdstringYesThe 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:
FieldTypeDescription
idstringThe unique batch identifier (UUID).
flywheelIdstringThe flywheel this batch belongs to.
tokenIdstringThe token ID associated with this batch.
mintAddressstringThe Solana mint address for the token.
statusstringCurrent batch status (see status values below).
batchIndexstringThe multisig batch index used for execution.
vaultIndexstringThe vault index within the multisig.
multisigstringThe multisig wallet address.
vaultAddressstringThe vault address for token operations.
initResultObject(Optional) Results from the batch initialization process.
executeResultObject(Optional) Results from the batch execution process.
dateCreatedstringISO 8601 timestamp when the batch was created.
dateUpdatedstringISO 8601 timestamp when the batch was last updated.

​
Batch Status Values

StatusDescription
AVAILABLE_TO_QUEUEBatch has been created but not yet finalized for execution.
FINALIZEDBatch has been finalized and is ready for execution approval.
EXECUTEDBatch has been successfully executed.
FAILEDBatch execution failed.

​
Init Result Object (Optional)

Present when status is FINALIZED or later.
FieldTypeDescription
totalnumberTotal number of setup transactions processed.
totalSuccessfulnumberNumber of setup transactions that succeeded.
totalFailednumberNumber of setup transactions that failed.
successfulExecutionsArrayArray of successful bundle executions during setup.
failedTxMsgstring(Optional) Error message if setup failed.
batchIndexnumberThe batch index used in the multisig.

​
Execute Result Object (Optional)

Present when status is EXECUTED or FAILED.
FieldTypeDescription
totalnumberTotal number of pipeline transactions.
totalSuccessfulnumberNumber of pipeline transactions that executed successfully.
totalFailednumberNumber of pipeline transactions that failed.
successfulExecutionsArrayArray of successful bundle executions.
failedOnTransactionIndexnumber(Optional) Transaction index where failure occurred.
failedStartTransactionIndexnumber(Optional) Starting index of the failed transaction batch.
failedTxMsgstring(Optional) Error message describing the failure.

​
Example Response (Finalized Batch)

{
  "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)

{
  "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 CodeStatusDescription
ERR_BATCH_NOT_FOUND404No batch exists with the provided batch ID.

​
Example Error Response

{
  "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.