Get Batch Status

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)

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

Monitor Batch Progress: Check if a batch has moved from FINALIZED to EXECUTED status.
Retrieve Execution Results: Get detailed transaction hashes and bundle IDs after execution.
Debug Failed Batches: Examine error messages and failure details when status is FAILED.
Audit Trail: Review the complete lifecycle of a batch operation with timestamps.
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

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

Authorizations

x-believe-api-key

string

header

required

Path Parameters

batchId

string<uuid>

required

The UUID of the batch to retrieve status for.

Response

Successful batch status retrieval.

string

required

The unique batch identifier (UUID).

flywheelId

string

required

The flywheel this batch belongs to.

tokenId

string

required

The token ID associated with this batch.

mintAddress

string

required

The Solana mint address for the token.

status

enum<string>

required

Current batch status.

Available options:

AVAILABLE_TO_QUEUE,

FINALIZED,

EXECUTED,

FAILED

batchIndex

string

required

The multisig batch index used for execution.

vaultIndex

string

required

The vault index within the multisig.

multisig

string

required

The multisig wallet address.

vaultAddress

string

required

The vault address for token operations.

dateCreated

string<date-time>

required

ISO 8601 timestamp when the batch was created.

dateUpdated

string<date-time>

required

ISO 8601 timestamp when the batch was last updated.

initResult

object

Results from the batch initialization process (optional).

Show child attributes

initResult.total

number

required

Total number of setup transactions processed.

initResult.totalSuccessful

number

required

Number of setup transactions that succeeded.

initResult.totalFailed

number

required

Number of setup transactions that failed.

initResult.successfulExecutions

object[]

required

Array of successful bundle executions during setup.

Show child attributes

initResult.successfulExecutions.bundleId

string

required

Jito bundle ID (hex string) for this group of transactions.

initResult.successfulExecutions.txHashes

string[]

required

Array of Solana transaction signatures (base58 strings) for executed transactions.

initResult.batchIndex

number

required

The batch index used in the multisig.

initResult.failedTxMsg

string

Error message if setup failed (optional).

executeResult

object

Results from the batch execution process (optional).

Show child attributes

executeResult.total

number

required

Total number of pipeline transactions in the batch.

executeResult.totalSuccessful

number

required

Number of pipeline transactions that executed successfully.

executeResult.totalFailed

number

required

Number of pipeline transactions that failed to execute.

executeResult.successfulExecutions

object[]

required

Array of successful bundle executions with their details.

Show child attributes

executeResult.successfulExecutions.bundleId

string

required

Jito bundle ID (hex string) for this group of transactions.

executeResult.successfulExecutions.txHashes

string[]

required

Array of Solana transaction signatures (base58 strings) for executed transactions.

executeResult.failedOnTransactionIndex

number

Transaction index where failure occurred (optional).

executeResult.failedStartTransactionIndex

number

Starting transaction index of the failed batch (optional).

executeResult.failedTxMsg

string

Error message describing the failure (optional).

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Overview

Authentication

Rate Limiting

Path Parameters

Example Request

Response Body

Batch Status Values

Init Result Object (Optional)

Execute Result Object (Optional)

Example Response (Finalized Batch)

Example Response (Executed Batch)

Use Cases

Error Codes

Example Error Response

Integration Tips

Authorizations

Path Parameters

Response

API Documentation

Flywheel V1

Tokenomics (Deprecated)

​Overview

​Authentication

​Rate Limiting

​Path Parameters

​Example Request

​Response Body

​Batch Status Values

​Init Result Object (Optional)

​Execute Result Object (Optional)

​Example Response (Finalized Batch)

​Example Response (Executed Batch)

​Use Cases

​Error Codes

​Example Error Response

​Integration Tips

Authorizations

Path Parameters

Response

Overview

Authentication

Rate Limiting

Path Parameters

Example Request

Response Body

Batch Status Values

Init Result Object (Optional)

Execute Result Object (Optional)

Example Response (Finalized Batch)

Example Response (Executed Batch)

Use Cases

Error Codes

Example Error Response

Integration Tips