Bulk Timelines

Bulk Timelines runs the Timelines query for up to 50,000 locations in one request, and delivers the result as a file to your own bucket. Use it instead of many separate Timelines calls when you need weather data for a large set of locations. You can run an order once (on demand) or on a cron schedule, for example a new 5-day forecast for all your locations every 6 hours.

How it works:

1. Set up your bucket. Contact Tomorrow.io for setting credentials. Refer to Destination.
2. Create an order with your locations (or a assets feed), fields, time window, format and destination.
3. Track the run until it is complete.
4. Get the files from your bucket.

Create an order

Body parameters

Request Example

curl -X POST "https://api.tomorrow.io/v4/data/orders/timelines?apikey=$TOMORROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warehouses-next-3-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": "nowPlus3d",
    "units": "metric",
    "format": "csv",
    "destination": { "type": "gcs", "bucket": "my-weather-exports", "prefix": "tomorrow" }
  }'

Response 201 Created for an on-demand order:

{
  "orderId": "ord-<accountId>-1a2b3c4d",
  "name": "warehouses-next-3-days",
  "runId": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "dataset": "timelines",
  "size": null
}

size is always null for timelines orders. name is present only when you set one.

When you create an order, the API checks your query with the Timelines API. An unknown field name or a timezone that is not valid returns 400 invalid_field, and field names the problem. Thus you find query errors before a run starts.

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 in UTC. 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-<accountId>-5e6f7a8b",
  "dataset": "timelines",
  "nextRunTime": "2026-10-12T18:00:00Z",
  "size": null
}

• The minimum interval between runs is 5 minutes.
• A 6-field expression (with seconds), an expression that is not valid, or a schedule that runs more frequently than every 5 minutes returns 422 invalid_schedule with "limit": "5m0s".

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

If you do not set a prefix, the path starts with <bucket>/<accountId>/.

Data file

CSV has one row for each location, timestep and interval. The columns are id, location, timestep and startTime, followed by one column for each field in the order that you requested them.

id,location,timestep,startTime,temperature,windSpeed
,"[32.0853,34.7818]",1h,2026-01-01T00:00:00Z,23.21,6.74
,"[32.0853,34.7818]",1h,2026-01-01T01:00:00Z,23.46,7.07

• location is the location as you sent it: the [lat,lon] pair or "lat, lon" string, or the GeoJSON as compact JSON.
• id is the ID of a saved location (then location is empty), or the feed asset's key for a feed. For inline locations, id is empty.
• A field with no value is an empty cell.

JSON is one array with one object for each location. JSONL has the same objects, one on each line. Each object has id and location (as in CSV, each only when it has a value) and timelines, which is the same as data.timelines in a Timelines API response:

{
  "location": [32.0853, 34.7818],
  "timelines": [
    {
      "timestep": "1h",
      "startTime": "2026-01-01T00:00:00Z",
      "endTime": "2026-01-06T00:00:00Z",
      "intervals": [
        { "startTime": "2026-01-01T00:00:00Z", "values": { "temperature": 23.21, "windSpeed": 6.74 } }
      ]
    }
  ]
}

failures.json

{
  "order_id": "ord-<accountId>-1a2b3c4d",
  "run_id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "locations_total": 1000,
  "locations_failed": 1,
  "failures": [
    { "location": "40.7128, -74.0060", "reason": "rate_limited", "status": 429, "message": "..." }
  ]
}

Each failure has reason and message. location_id is present for a saved location or a feed asset, and location is present for an inline location.

credits.json

error.json

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. You can read a run for approximately 30 days.

{
  "runId": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "status": "completed",
  "outcome": "partial",
  "outcomeReason": "insufficient_credits"
}

On a completed run, outcome: partial means that some locations are not in the data file, and failures.json lists them. outcomeReason: insufficient_credits means that some of them failed because your account did not have enough credits.

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 a scheduled order. Future runs do not start. A run that is in progress continues.
• {"active": true} resumes a scheduled order.
• {"name": "new-name"} renames the order.

An order that you created with "active": false must be activated with {"active": true} before you can change anything else. Until then, other changes return 409 run_pending. When you activate it, an on-demand order starts its run, and a scheduled order starts to run at its next tick.

To change the locations, fields, time window or schedule, create a new order.

Limits

Errors

All error responses from the API 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, and limit is the limit that was exceeded or the list of valid values. Not all errors have field and limit.