---
updatedAt: 2025-07-07T05:33:27.000Z
agentTools:
  projectIndex: https://docs.tomorrow.io/llms.txt
---

# Historical API

![](https://files.readme.io/cf5079a-Historical-API.png "Historical-API.png")

Tomorrow\.io's Historical Weather API allows you to query weather conditions (limited to [historical data layers](https://docs.tomorrow.io/reference/historical)) by specifying the `location` (GeoJSON of a Point, LineString or Polygon), `fields` ("temperature", "windSpeed", ...), `timesteps` ("1h", "1d") and the `startTime` and `endTime`, such that the response includes a historical timeline.

## Limitations:

| All Users                                               | Polygon/Polyline Users                                        | Token System Users     |
| :------------------------------------------------------ | :------------------------------------------------------------ | :--------------------- |
| **Timerange** is limited to up to 31 days per API call. | Polygon - 10,000 square km and no more than 70km per segment. | 10 fields per api call |
|                                                         | Polyline - 2,000 km long.                                     |                        |
|                                                         | Max number of vertices - 550.                                 |                        |

If the location is a Polygon or a Polyline, you can specify whether you want the min/max/avg values throughout that coverage area by adding them as a suffix to any of the available fields (`temperatureMax`, temperatureMaxTime) and if not specified the response will default to `Max`.

**The historical archive is based on a reanalysis model that blends past short-range weather forecasts with observations through advanced data assimilation techniques. The historical archive data deviates from the recent historical data -7 days since it is based on a different observation data assimilation system that incorporates a larger set of final observational records.**\
Please note that our reanalysis model takes between 7 to 90 days to calculate the data fields. Please see the historical data field [Availability](https://docs.tomorrow.io/reference/historical).

## Tokens Usage Mechanism:

The Historical API operates on the Tomorrow\.io [Token System](https://docs.tomorrow.io/reference/rate-limiting#tokens). Each request deducts tokens from the 'historical' tokens balance. The number of tokens deducted and the number of remaining tokens are included in the [response headers](https://docs.tomorrow.io/reference/rate-limiting#tokens) with the following keys:

* X-Tokens-Cost-historical
* X-Tokens-Remaining-historical

Point location Request deducts- 1 token.

Polygon request deducts- 10 tokens