> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Granularity & Time Ranges

> Pick a granularity in the path and a time window with timeframe or start/end. Every timeseries endpoint accepts the same time-selection parameters.

Every timeseries request answers two questions: at what resolution, and over what window. The
**granularity** is a path segment; the **time window** is a query parameter.

```
GET /query/timeseries/{model}/{granularity}?timeframe=30d
                                └ resolution  └ window
```

## Granularity

Granularity is part of the URL path, not a query parameter:

```
GET /query/timeseries/asset-price/1d/1e31218a-e44e-4285-820c-8282ee222035
GET /query/timeseries/asset-price/1h/1e31218a-e44e-4285-820c-8282ee222035
```

| Token | Interval         |
| ----- | ---------------- |
| `5m`  | 5 minutes        |
| `1h`  | 1 hour           |
| `6h`  | 6 hours          |
| `1d`  | 1 day            |
| `1w`  | 1 week           |
| `1n`  | 1 calendar month |

<Warning>
  **Each model supports only a subset of these.** `1d` is the most widely available; some models add
  `1w` or `1h`, and only a handful go down to `5m`. Requesting a granularity a model does not offer
  returns `404`.
</Warning>

Read the supported set from the model's `intervals` array in the
[timeseries catalog](/getting-started/concepts/catalog), or from the `granularity` path parameter's
enum on the endpoint's reference page.

```bash theme={null}
curl -s 'https://api.blockworks.com/query/timeseries/catalog' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  | jq '.data.models[] | select(.slug=="asset-price") | .intervals'
```

```json theme={null}
["5m", "1h", "1d", "1w"]
```

<Note>
  `1n` is a legacy token for a calendar month, carried over from earlier API versions and still used
  by a few monthly models (fundraising, for example). Where it appears in a model's `intervals`, it
  is the correct value to put in the path.
</Note>

## Time windows

There are two mutually exclusive ways to select a window: `timeframe`, or `start`/`end`.

<Warning>
  Combining them returns `400` with `cannot combine timeframe with start/end`. Pick one style per
  request.
</Warning>

If you supply neither, the window is unbounded below and ends at the current time: you get
everything the API retains for that series.

### `timeframe`

A single expressive token. Windows anchored to "now" end at the current time.

| Form            | Examples                          | Resolves to                                                                 |
| --------------- | --------------------------------- | --------------------------------------------------------------------------- |
| To-date         | `ytd`, `htd`, `qtd`, `mtd`, `dtd` | From the start of the calendar year, half, quarter, month, or day up to now |
| Relative        | `30d`, `12h`, `3w`, `90m`         | From that duration ago up to now                                            |
| Calendar day    | `2026-07-13`                      | That whole day                                                              |
| Calendar month  | `2026-07`                         | That whole month                                                            |
| Calendar year   | `2026`                            | That whole year                                                             |
| RFC3339 instant | `2026-07-13T00:00:00Z`            | From that instant up to now                                                 |
| Unix seconds    | `1783843200`                      | From that instant up to now                                                 |

Relative windows accept the units `m` (minutes), `h` (hours), `d` (days), and `w` (weeks), written
as a count followed by the unit. Tokens are case-insensitive: `YTD` and `30D` work.

<Warning>
  **There is no year or month unit.** `1y` and `1M` return `400` with `unrecognized timeframe "1y"`.
  For the last year use `365d` or `52w`; for the calendar year to date use `ytd`; for a whole past
  year or month use the calendar forms `2025` or `2025-06`; for anything else use `start`/`end`.
</Warning>

In full, `timeframe` accepts exactly these forms:

| Form           | Pattern                                                          |
| -------------- | ---------------------------------------------------------------- |
| To-date        | `ytd`, `htd`, `qtd`, `mtd`, `dtd`                                |
| Relative       | `<n>m`, `<n>h`, `<n>d`, `<n>w` (a positive integer and one unit) |
| Calendar day   | `YYYY-MM-DD`                                                     |
| Calendar month | `YYYY-MM`                                                        |
| Calendar year  | `YYYY` between 1970 and 3000                                     |
| Instant to now | an RFC3339 timestamp, or any other integer read as unix seconds  |

```bash theme={null}
# Year to date, daily
curl -G 'https://api.blockworks.com/query/timeseries/asset-price/1d/1e31218a-e44e-4285-820c-8282ee222035' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --data-urlencode 'timeframe=ytd'

# The last 12 hours, hourly
curl -G 'https://api.blockworks.com/query/timeseries/asset-price/1h/1e31218a-e44e-4285-820c-8282ee222035' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --data-urlencode 'timeframe=12h'
```

<Note>
  A bare number is read as a calendar year when it falls between 1970 and 3000, and as a unix
  timestamp otherwise. If you mean a specific instant inside that range, use RFC3339 or `start`.
</Note>

### `start` and `end`

For explicit windows. Each accepts RFC3339, unix seconds, or `YYYY-MM-DD`. Both are optional: an
omitted `start` leaves the window unbounded below, and an omitted `end` defaults to now.

```bash theme={null}
curl -G 'https://api.blockworks.com/query/timeseries/asset-price/1d/1e31218a-e44e-4285-820c-8282ee222035' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --data-urlencode 'start=2026-01-01' \
  --data-urlencode 'end=2026-06-30'
```

A `start` later than `end` returns `400`.

<Note>
  Windows are half-open: `[start, end)`. A calendar expansion such as `timeframe=2026-07-13` runs
  from that midnight up to, but not including, the next, so adjacent windows never double-count a
  bucket.
</Note>

## `bounds`

Set `bounds=true` to return only the **first and last** point of the resolved window instead of
every point in it. This is the efficient way to compute a change over a period without transferring
the whole series.

```bash theme={null}
curl -G 'https://api.blockworks.com/query/timeseries/asset-price/1d/1e31218a-e44e-4285-820c-8282ee222035' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --data-urlencode 'timeframe=ytd' \
  --data-urlencode 'bounds=true'
```

## Timestamps in the response

Every point begins with a **unix timestamp in seconds**, in UTC. The values that follow are the
metrics in `point_schema` order. See [Responses](/getting-started/responses#reading-points).

## Choosing a granularity

<CardGroup cols={2}>
  <Card title="Match the window" icon="ruler">
    A year of `5m` data is a very large response. Use `1d` for long windows and reserve fine
    granularities for short ones.
  </Card>

  <Card title="Check what exists" icon="list-check">
    Read `intervals` from the catalog before hardcoding a granularity, because the supported set
    differs per model.
  </Card>
</CardGroup>

For long windows at fine granularity, request `acceptFormat=csv` or `acceptFormat=jsonl` to receive
the data as a downloadable file rather than a single JSON document. See
[Filtering & pagination](/getting-started/filtering-pagination#response-formats).