​
Overview

The Get Current Batch endpoint retrieves the currently active flywheel batch for a specified token. This is useful for checking if there’s already an ongoing batch operation before creating a new one, or for getting the status of the current batch without needing to know the specific batch ID. Returns null if no current batch exists for the token.

​
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.

​
Request Body

FieldTypeRequiredDescription
tokenIdstringYesThe token ID to retrieve the current batch for.

​
Example Request

{
  "tokenId": "token_def456"
}

​
Response Body

On success, the API returns either:
  • A JSON object containing the current batch information (same structure as /batch/{batchId})
  • null if no current batch exists for the token

​
Example Response (Current Batch Exists)

{
  "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": [
          "3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1JqJ8LoX2GbM4aC9eR",
          "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC"
        ]
      }
    ],
    "batchIndex": 42
  },
  "dateCreated": "2025-01-27T12:00:00.000Z",
  "dateUpdated": "2025-01-27T12:05:00.000Z"
}

​
Example Response (No Current Batch)

null

​
Batch Status Values

When a current batch exists, it will have one of these 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 (may still be “current” briefly).
FAILEDBatch execution failed.

​
Use Cases

  1. Pre-Creation Check: Verify no active batch exists before creating a new one.
  2. Status Monitoring: Get the current batch status without needing to store batch IDs.
  3. Workflow Management: Determine if your application should wait for current operations to complete.
  4. Error Recovery: Check if a batch is stuck in a particular state and needs intervention.
  5. Dashboard Display: Show users the current state of their token’s flywheel operations.

​
Integration Patterns

​
Before Creating New Batch

// Check for current batch before creating new one
const currentBatch = await getCurrentBatch(tokenId);

if (currentBatch) {
  if (currentBatch.status === "FINALIZED") {
    // Wait for execution or execute it
    console.log("Batch ready for execution:", currentBatch.id);
  } else if (currentBatch.status === "EXECUTED") {
    // Previous batch completed, safe to create new one
    await createNewBatch(pipelines);
  } else {
    // Batch still in progress
    console.log("Batch in progress:", currentBatch.status);
  }
} else {
  // No current batch, safe to create new one
  await createNewBatch(pipelines);
}

​
Status Monitoring Loop

// Monitor current batch until completion
let currentBatch;
do {
  currentBatch = await getCurrentBatch(tokenId);
  if (currentBatch && currentBatch.status === "FINALIZED") {
    console.log("Batch ready for execution");
    break;
  }
  await sleep(5000); // Wait 5 seconds
} while (currentBatch && currentBatch.status !== "EXECUTED");

​
Error Codes

The current batch endpoint can return specific error codes.
Error CodeStatusDescription
ERR_BATCH_CURRENT_FAILED500Failed to retrieve current batch information.

​
Example Error Response

{
  "error": "ERR_BATCH_CURRENT_FAILED",
  "message": "Database connection failed"
}

​
Important Notes

  1. Null Response: A null response is normal and indicates no current batch exists for the token.
  2. Current Definition: A batch is considered “current” if it’s the most recent batch that hasn’t reached a final state.
  3. State Transitions: Once a batch reaches EXECUTED or FAILED status, it may no longer be considered “current” depending on your implementation.
  4. Race Conditions: In high-frequency applications, check for current batch immediately before creating new ones to avoid conflicts.
  5. Token Scoping: This endpoint only returns batches for the specific token ID provided, ensuring proper isolation between different tokens.