# Dates and time zones in the API

> How the Ranqo API sets a report window, where its days start and end, how a window with no run is read, and how timestamps are written.

Source: https://ranqo.ai/docs/api/dates-and-time-zones

The reports (`/visibility`, `/competitors`) and a prompt's answers count the answers in a window of days. You choose the window and the time zone its days follow.

## Choosing a window

Send either a preset or two dates, not both:

- **`period`**: one of 7d, 30d, 90d, and 365d. Without either, the window is `30d`.
- **`start_date` and `end_date`**: whole days as `YYYY-MM-DD`, both included, at most 366 days apart counting both.

The presets match the Visibility page's date picker. `7d`, `30d` and `90d` start at midnight that many days ago and run to now. `365d` starts at midnight 365 days ago and runs to the end of today. Custom dates run from midnight of the first day to the end of the last.

## Time zones

`tz` sets where a day starts: an IANA name such as `America/New_York` or `Asia/Kolkata`, and `UTC` when you leave it out. A name that is not a time zone is refused with `invalid_parameter`, rather than read as UTC.

Days follow the zone's clock changes, so a day in a zone that moves its clocks starts at the local midnight, as a browser in that zone counts it. See [Time zones](https://ranqo.ai/docs/methodology/time-zones) for how the dashboard does the same.

## The window before

Reports compare the window with the one before it, from `window.previous_start` to `window.start`: the same number of whole days for a preset, the same length for custom dates. The compared figures carry their `current` and `previous` values and the `change` between them: the four headline figures of a visibility report, and each brand's `visibility` in a competitors report. Everything else, such as the distributions, the breakdown rows and a competitor's position, sentiment and share of voice, describes the window alone.

## A window with no run

A brand is tracked every 7 days, so a short window can hold no completed run. The report then reads the latest run before the window: `window.carried_from` holds when that run completed, and nothing is compared, so `previous` and `change` are `null`. The dashboard shows the same figures labelled *as of* that date. See [Carried values](https://ranqo.ai/docs/methodology/carried-values).

## Timestamps

Every timestamp is RFC 3339 in UTC, such as `2026-09-28T14:05:00.000Z`, whatever `tz` you send. The time zone changes where a window's days begin, not how times are written.

## Freshness

A report is kept for 10 minutes for the same window, filters and day, and replaced as soon as a new run completes. A watchlist change or a competitor renamed in the dashboard shows within that time.