Using the API
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.
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 is30d.start_dateandend_date: whole days asYYYY-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 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.
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.