# Block API Reference

OpenAPI source: https://api.are.na/v3/openapi.json

## GET /v3/blocks/batch/{batch_id}

- Label: Get batch status
- Docs: https://www.are.na/developers/explore/block/{batch_id}
- Markdown: https://www.are.na/developers/explore/block/{batch_id}.md
- Requires resource id: no
- Response content type: application/json

Returns the current status of a batch block creation job.
Poll this endpoint to track progress and retrieve results.

Batch results are available for 24 hours after submission.

**⚠️ Premium Only**: This endpoint requires a Premium subscription.

Path parameters:
- batch_id: string (required) — The batch ID returned from the batch create endpoint

Response schema:
```json
{
  "type": "object",
  "description": "Current status of a batch processing job",
  "required": [
    "batch_id",
    "status",
    "total",
    "successful_count",
    "failed_count"
  ],
  "properties": {
    "batch_id": {
      "type": "string",
      "nullable": false,
      "description": "Unique identifier for this batch",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "nullable": false,
      "description": "Current processing status",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ]
    },
    "total": {
      "type": "integer",
      "nullable": false,
      "description": "Total number of blocks in the batch"
    },
    "successful_count": {
      "type": "integer",
      "nullable": false,
      "description": "Number of blocks created so far"
    },
    "failed_count": {
      "type": "integer",
      "nullable": false,
      "description": "Number of blocks that failed"
    },
    "successful": {
      "type": "array",
      "description": "Successfully created blocks",
      "items": {
        "type": "object",
        "required": [
          "index",
          "block_id"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "nullable": false,
            "description": "Original index in the request array"
          },
          "block_id": {
            "type": "integer",
            "nullable": false,
            "description": "ID of the created block"
          }
        }
      }
    },
    "failed": {
      "type": "array",
      "description": "Blocks that failed to create",
      "items": {
        "type": "object",
        "required": [
          "index",
          "error"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "nullable": false,
            "description": "Original index in the request array"
          },
          "error": {
            "type": "string",
            "nullable": false,
            "description": "Error message"
          }
        }
      }
    },
    "created_at": {
      "type": "string",
      "nullable": false,
      "description": "When the batch was submitted",
      "format": "date-time"
    },
    "completed_at": {
      "type": "string",
      "nullable": false,
      "description": "When the batch finished processing (present when completed or failed)",
      "format": "date-time"
    },
    "error": {
      "type": "string",
      "nullable": false,
      "description": "Top-level error message if the entire batch failed"
    }
  },
  "refName": "BatchStatus"
}
```