Bulk Timelines

Bulk Timelines runs the Timelines query for many locations at once. The result is delivered as one file to your own bucket. You can run an order once (on demand) or on a cron schedule.

Create an order

curl -X POST "https://api.tomorrow.io/v4/data/orders/timelines?apikey=$TOMORROW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: deflate, gzip, br" \
  -d '{
    "name": "warehouses-next-5-days",
    "locations": [
      [32.0853, 34.7818],
      "40.7128, -74.0060",
      { "type": "Polygon", "coordinates": [[[-0.2,51.4],[0.1,51.4],[0.1,51.6],[-0.2,51.6],[-0.2,51.4]]] }
    ],
    "fields": ["temperature", "windSpeed", "precipitationIntensity"],
    "timesteps": ["1h"],
    "start": "now",
    "end": "nowPlus5d",
    "units": "metric",
    "timezone": "UTC",
    "format": "csv",
    "destination": { "type": "gcs", "bucket": "my-weather-exports", "prefix": "tomorrow" }
  }'

Response 201 Created for an on-demand order:

{
  "orderId": "ord_8c1f2a",
  "name": "warehouses-next-5-days",
  "runId": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "dataset": "timelines",
  "size": null
}

Body parameters

Destination

{ "type": "gcs", "bucket": "my-bucket", "prefix": "optional/prefix" }

Scheduled orders

To make a recurring export, add a trigger with a 5-field cron expression. The request does not start a run. The response has nextRunTime and no runId.

Request for example:

{
  "feedId": "my-sites-feed",
  "fields": ["temperature", "humidity"],
  "timesteps": ["1h"],
  "start": "now",
  "end": "nowPlus2d",
  "format": "jsonl",
  "destination": { "type": "s3", "bucket": "my-weather-exports" },
  "trigger": { "type": "schedule", "schedule": "0 */6 * * *" }
}

Response:

{
  "orderId": "ord_9d2e3b",
  "dataset": "timelines",
  "nextRunTime": "2026-10-12T18:00:00Z",
  "size": null
}

Delivered files

Each run writes its files to a folder for that run. A new run never overwrites the files of an earlier run.

<bucket>/<prefix>/<accountId>/<orderId>/<runId>/timelines.<csv|json|jsonl>
<bucket>/<prefix>/<accountId>/<orderId>/<runId>/failures.json
<bucket>/<prefix>/<accountId>/<orderId>/<runId>/credits.json
<bucket>/<prefix>/<accountId>/<orderId>/<runId>/error.json

Example timelines.csv:

id,lat,lon,timestep,startTime,temperature,windSpeed
tel-aviv,32.0853,34.7818,1h,2026-01-01T00:00:00Z,23.21,6.74
tel-aviv,32.0853,34.7818,1h,2026-01-01T01:00:00Z,23.46,7.07

Example failures.json:

{
  "order_id": "ord_8c1f2a",
  "run_id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "locations_total": 1000,
  "locations_failed": 1,
  "failures": [
    { "location_id": "site-17", "reason": "location_not_found", "status": 400, "message": "..." }
  ]
}

The values of reason in failures.json are location_not_found, invalid_request, not_entitled, rate_limited, upstream_unavailable and unknown.

The values of code in error.json are permission_denied, feed_not_found, too_many_locations, invalid_order and invalid_query. invalid_query means that every location failed with the same query error, for example an unknown field or an incorrect timezone.

Track a run

GET https://api.tomorrow.io/v4/data/orders/timelines/{orderId}/runs/{runId}?apikey=<YOUR_API_KEY>

Poll this endpoint until the status is completed, failed, cancelled or skipped.

{
  "runId": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "status": "completed",
  "fileCount": 1,
  "filesDelivered": 1
}

Manage orders and runs

All paths start with https://api.tomorrow.io/v4 and need the apikey query parameter.

Pause, resume or rename an order

curl -X PATCH "https://api.tomorrow.io/v4/data/orders/timelines/{orderId}?apikey=$TOMORROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

• {"active": false} pauses the order. Future runs do not start. A run that is in progress continues.
• {"active": true} resumes the order. If the order was created with "active": false, this starts it for the first time.
• {"name": "new-name"} renames the order.

Limits

Errors

All error responses have the same structure:

{
  "code": "too_many_locations",
  "field": "locations",
  "limit": 50000,
  "message": "..."
}

Use code in your logic, because its values do not change. field is the request field that caused the error. limit is the limit that was exceeded, or the list of valid values.