Batch Requests

This document provides an overview of the Batch Request API endpoints for managing and fulfilling batch data requests.

1. Retrieve Pending Batch Requests

Endpoint

GET https://$ORG_BASE_URL/batch-requests?status=1

Description

This endpoint retrieves a list of batch requests that require fulfillment. The response includes batch requests currently marked as PENDING.

Response Format

[
  {
    "request_id": "b0b48ae3-bfe8-480e-a9ca-424b9b4e0662",
    "start_time": "2024-04-18T11:40:27.874Z",
    "end_time": "2024-04-18T13:50:27.874Z",
    "status": "PENDING"
  },
  {
    "request_id": "532a5e22-da28-4b4e-8b7d-6d81f0f47079",
    "start_time": "2024-04-18T11:40:27.874Z",
    "end_time": "2024-04-18T14:50:27.874Z",
    "status": "PENDING"
  }
]

Success Response

Status Code: 200 OK

Error Responses

401 Unauthorized: Authentication credentials are missing or invalid.
500 Internal Server Error: An unexpected error occurred.

Example Usage (Using curl)

curl --location "https://$ORG_BASE_URL/batch-requests?status=1" \
--header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

2. Update Batch Request Status

Endpoint

PATCH https://$ORG_BASE_URL/batch-requests/{request_id}

Description

This endpoint allows updating the status of a batch request.

Request Body Format

{
  "status": "IN_PROGRESS"
}

Status Options

PENDING - The batch request has not yet been picked up.
IN_PROGRESS - The batch request is currently being processed.
COMPLETED - The batch request has been successfully fulfilled.
FAILED - The batch request could not be completed.

Success Response

Status Code: 200 OK

{
  "request_id": "532a5e22-da28-4b4e-8b7d-6d81f0f47079",
  "start_time": "2024-04-18T11:40:27.874Z",
  "end_time": "2024-04-18T13:50:27.874Z",
  "status": "IN_PROGRESS"
}

Error Responses

400 Bad Request: The provided status is invalid.
404 Not Found: The specified batch request does not exist.
401 Unauthorized: Authentication credentials are missing or invalid.
500 Internal Server Error: An unexpected error occurred.

Example Usage (Using curl)

curl --location --request PATCH "https://$ORG_BASE_URL/batch-requests/532a5e22-da28-4b4e-8b7d-6d81f0f47079" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
--data '{ "status": "IN_PROGRESS" }'

Authentication & Security

All API requests must include a valid authentication token in the Authorization header.
Unauthorized requests will return a 401 Unauthorized response.
API keys or tokens should be securely stored and never exposed publicly.

Notes

Clients must ensure that a batch request is processed only once to prevent duplicate processing. This can be managed by promptly updating the batch request status to IN_PROGRESS after claiming it.
All FAILED requests will automatically revert to PENDING after a predefined backoff period, handled by the backfill pipeline.
The system employs a late acknowledgment strategy by default. Any IN_PROGRESS requests will be automatically reset to PENDING after a specified TIME_LIMIT. This setting is configurable at the system level based on client's requirements.
Status transitions must follow the correct sequence: PENDING → IN_PROGRESS → COMPLETED or FAILED.

Turbomechanica Docs