Batch Requests

Execute multiple computation requests in a single HTTP call. Reduces HTTP overhead for common patterns like computing positions across a date range.

Text

POST /v1/batch

Credit cost: Sum of individual sub-request costs (no surcharge)

Request Body

JSON

{
  "requests": [
    {
      "endpoint": "/v1/positions",
      "params": {
        "datetime": "2024-01-01T00:00:00Z",
        "bodies": "sun,moon"
      }
    },
    {
      "endpoint": "/v1/houses",
      "params": {
        "datetime": "2024-01-01T00:00:00Z",
        "lat": 40.7128,
        "lon": -74.006
      }
    }
  ]
}

Field	Type	Required	Description
`requests`	array	Yes	Array of sub-request objects (1 to 50)
`requests[].endpoint`	string	Yes	API endpoint path (e.g., `"/v1/positions"`)
`requests[].params`	object	Yes	Endpoint-specific parameters

Limits

Constraint	Value
Max sub-requests	50
Method	POST only
Nested batch	Not allowed (`/v1/batch` cannot be a sub-request)

Allowed Endpoints

Any /v1/* computation endpoint:

Endpoint	Credit Cost
`/v1/positions`	1
`/v1/houses`	1
`/v1/chart`	1
`/v1/stars`	1 (single), 5 (all)
`/v1/ayanamsha`	1
`/v1/delta-t`	1
`/v1/sidereal-time`	1
`/v1/eclipses/solar`	3
`/v1/eclipses/lunar`	2
`/v1/heliacal`	3
`/v1/ingresses`	2

Response

JSON

{
  "data": {
    "results": [
      {
        "index": 0,
        "status": 200,
        "data": [
          {
            "body": "sun",
            "longitude": 280.35,
            "latitude": 0.0001,
            "distance": 0.9833,
            "speed": 1.0194,
            "sign": "Capricorn",
            "sign_degree": 10.35,
            "retrograde": false,
            "declination": -23.01,
            "out_of_bounds": false
          }
        ],
        "warnings": null
      },
      {
        "index": 1,
        "status": 200,
        "data": {
          "system": "Placidus",
          "cusps": [280.5, 311.2, 345.8, 17.1, 46.3, 72.9, 100.5, 131.2, 165.8, 197.1, 226.3, 252.9],
          "ascendant": 280.5,
          "midheaven": 197.1,
          "armc": 198.2,
          "vertex": 89.7,
          "warnings": null
        },
        "warnings": null
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  },
  "meta": {
    "version": "1.0-beta",
    "request_id": "a1b2c3d4-...",
    "timestamp": "2024-01-15T12:00:00.000Z",
    "credits_used": 2,
    "credits_remaining": 498,
    "computation_ms": 0.0
  }
}

Field	Type	Description
`data.results`	array	One entry per sub-request, in the same order as the input
`data.results[].index`	number	0-based position matching the input array
`data.results[].status`	number	HTTP status code for this sub-request (200, 400, etc.)
`data.results[].data`	object/array	Endpoint response data (present on success, absent on failure)
`data.results[].warnings`	array/null	Warnings from the computation, if any
`data.results[].error`	object/null	Error details (present on failure, absent on success)
`data.results[].error.code`	string	Machine-readable error code
`data.results[].error.message`	string	Human-readable error description
`data.results[].error.param`	string/null	The parameter that caused the error
`data.summary.total`	number	Total sub-requests in the batch
`data.summary.succeeded`	number	Sub-requests that returned status 200
`data.summary.failed`	number	Sub-requests that returned non-200 status

Error Handling

Batch-level errors (entire batch fails, no results returned):

Condition	Status	Error Code
Missing or invalid API key	401	`invalid_api_key`
Rate limit exceeded	429	`rate_limit_exceeded`
Insufficient credits for total cost	402	`insufficient_credits`
Empty `requests` array	400	`batch_empty`
More than 50 sub-requests	400	`batch_too_large`
Nested `/v1/batch` endpoint	400	`batch_nested_not_allowed`
Invalid JSON body	400	`invalid_parameter`

Sub-request errors (individual failures, other sub-requests still succeed):

Condition	Status	Error Code
Unknown endpoint	400	`invalid_parameter`
Missing required parameter	400	`missing_parameter`
Invalid parameter value	400	`invalid_parameter`
Computation failure	500	`computation_error`

Credit Calculation

Total credit cost is the sum of each sub-request's endpoint cost. Credits are checked and charged once before any sub-requests execute.

Example: 3 position requests (1 each) + 1 solar eclipse search (3) = 6 credits total.

Rate Limiting

A batch request counts as 1 request against the per-minute rate limiter, regardless of how many sub-requests it contains.

Notes

Sub-requests execute sequentially within the Worker. There is no parallel execution.
Each sub-request is independent — there is no way to share parameters across sub-requests. Build the array client-side with shared values.
The batch endpoint is POST-only. GET requests to /v1/batch are not supported.

Batch

On this page