Skip to main content

Ingest Location Batch

POST 
/api/v1/locations/batch

Ingest a batch of location points.

Accepts up to 5000 locations per batch. Each location is validated and processed asynchronously as a single batch task.

Register active devices first; API keys require devices:write. Admission counts each new fix toward the monthly event quota, which usage past the quota never refuses. A partially admitted batch returns 202 with accepted receipt IDs and indexed rejection errors, never a whole-request failure after accepting points. Exact fix retries reuse durable receipts for at least 48 hours after processing without another charge. Broker outages leave accepted work pending for automatic recovery.

A fix from a paused shift is rejected per item with the same status and error_code as POST /locations (SHIFT_PAUSED or PAUSED_INTERVAL), and is not stored, charged or evaluated.

Idempotency: If idempotency_key is provided, duplicate requests with the same key within 24 hours reuse the admission response without reprocessing. Terminal processing rejections, including a pause that began before a fix was processed, refresh the returned counts and indexed errors.

Authentication: API Key (Bearer token) Rate Limit: 100 batches/minute per API key

Returns: 202 Accepted: Locations queued (includes counts of accepted/rejected) 400 Bad Request: Invalid batch data 401 Unauthorized: Missing or invalid API key 429 Too Many Requests: Rate limit exceeded

Example:

curl -X POST https://api.spatialflow.io/api/v1/locations/batch \
  -H "Authorization: Bearer sf_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '\{
    "locations": [
      \{"device_id": "truck-005", "lat": 40.7589, "lon": -73.9851, "ts": "2025-10-01T14:30:00Z"\},
      \{"device_id": "truck-005", "lat": 40.7590, "lon": -73.9850, "ts": "2025-10-01T14:31:00Z"\}
    ],
    "idempotency_key": "batch-20251001-001"
  \}'

Request​

Responses​

Accepted