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

# Date Ranges & Timezones

> Understanding how to work with dates and timezones in the API

## Overview

All data in our system is stored in UTC, but our processing runs on an EST (Eastern Standard Time) schedule. Understanding how date ranges work is critical to querying the correct data for your use case.

<Warning>
  Incorrect timezone handling is the most common cause of missing or unexpected data in API responses. Please read this guide carefully.
</Warning>

## System Behavior

### Data Processing Schedule

Our system processes data according to the EST timezone:

* The "day" of January 1st EST starts at **00:00 EST** (05:00 UTC)
* The "day" of January 1st EST ends at **23:59 EST** (04:59 UTC next day)

All data is stored with UTC timestamps in our database.

### Date Format Support

The API accepts dates in multiple formats:

1. **Date only** (recommended for daily queries): `2025-01-01`
2. **Date and time without timezone**: `2025-01-01T00:00:00`
3. **Date and time with UTC timezone**: `2025-01-01T05:00:00Z`

## How Dates Are Interpreted

### Without Timezone Specification

When you provide a date **without a timezone** (no `Z` suffix), the API interprets it as **EST**:

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}
```

**What happens:**

* `2025-01-01` → Interpreted as `2025-01-01T00:00:00 EST` → Converted to `2025-01-01T05:00:00Z` UTC
* `2025-01-31` → Interpreted as `2025-01-31T00:00:00 EST` → Converted to `2025-01-31T05:00:00Z` UTC

This matches how our system defines "days" and is the **recommended approach** for most use cases.

### With UTC Timezone (Z suffix)

When you provide a date **with the Z suffix**, the API interprets it as **literal UTC**:

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
```

**What happens:**

* `2025-01-01T00:00:00Z` → Used as-is in UTC
* `2025-02-01T00:00:00Z` → Used as-is in UTC

<Warning>
  Using UTC timestamps (with Z) requires you to manually convert from EST to UTC. This approach exists for backwards compatibility but is **not recommended** for new integrations.
</Warning>

## Examples

### Correct: Query January 2025 data (EST days)

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
```

This returns all data from:

* Start: January 1st, 00:00 EST (05:00 UTC on Jan 1st)
* End: February 1st, 00:00 EST (05:00 UTC on Feb 1st)

The range is inclusive (`<=`), but since data typically doesn't have timestamps exactly at 00:00, this effectively captures all of January.

### Incorrect: Query January 2025 with UTC midnight

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
```

This returns data from:

* Start: December 31st, 19:00 EST (00:00 UTC on Jan 1st)
* End: January 31st, 19:00 EST (00:00 UTC on Feb 1st)

**Problem:** You're missing 5 hours at the start and including 5 hours you don't want at the end.

### Correct: Query January 2025 with UTC (manual conversion)

If you must use UTC timestamps, you need to account for the EST offset:

```json theme={null}
{
  "start_date": "2025-01-01T05:00:00Z",
  "end_date": "2025-02-01T05:00:00Z"
}
```

This correctly captures all of January (EST days), but requires manual timezone math.

## Time Ranges

### Date-only format defaults to midnight

When using date-only format, times default to `00:00:00`:

```json theme={null}
{
  "start_date": "2025-01-01"  // Equivalent to 2025-01-01T00:00:00 EST
}
```

### Specifying exact times

You can specify exact times for more granular queries:

```json theme={null}
{
  "start_date": "2025-01-01T08:00:00",  // 8 AM EST
  "end_date": "2025-01-01T17:00:00"     // 5 PM EST
}
```

This queries data from 8 AM to 5 PM EST on January 1st.

### Date range behavior

Date ranges are **inclusive** on both ends `(start <= x <= end)`:

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-02"
}
```

This includes:

* All of January 1st (from 00:00 EST onwards)
* January 2nd at exactly 00:00 EST
* Since data is timestamped throughout the day, there typically isn't data exactly at 00:00, so in practice this captures all of January 1st

To query a single day, set `end_date` to the next day at 00:00.

## Best Practices

<Check>
  **Recommended:** Use date-only format without timezone for daily queries
</Check>

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
```

<Check>
  **Recommended:** Use datetime without timezone for intraday queries
</Check>

```json theme={null}
{
  "start_date": "2025-01-15T09:00:00",
  "end_date": "2025-01-15T17:00:00"
}
```

<Check>
  **Recommended:** Use datetime without timezone for hourly report queries (via [Agent Analytics](/rest-api/examples/agent-analytics) **V2 (hourly)** tab)
</Check>

```json theme={null}
{
  "start_date": "2025-01-15T14:00:00",
  "end_date": "2025-01-15T14:59:59"
}
```

<Warning>
  **Fractional-offset timezone users:** When querying at hour-level granularity with `/v2/reports/*`, query 2 consecutive hours to get complete data for a single local hour. See [Fractional-Offset Timezones](#fractional-offset-timezones) for details.
</Warning>

<Warning>
  **Avoid:** Using Z suffix unless you understand UTC offset implications
</Warning>

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",  // Probably not what you want
  "end_date": "2025-02-01T00:00:00Z"
}
```

## Daylight Saving Time

EST observes Daylight Saving Time (DST):

* **Standard Time (EST):** UTC-5 (typically November - March)
* **Daylight Time (EDT):** UTC-4 (typically March - November)

The API automatically handles DST transitions. When you specify dates without timezone, the conversion to UTC accounts for whether DST was active on that date.

**Example during DST:**

```json theme={null}
{
  "start_date": "2025-07-01"  // Interpreted as EDT (UTC-4)
}
```

→ Converted to `2025-07-01T04:00:00Z` UTC (not 05:00 because of DST)

## Fractional-Offset Timezones

Some timezones use fractional UTC offsets rather than whole-hour offsets:

| Timezone                  | UTC Offset |
| ------------------------- | ---------- |
| India Standard Time (IST) | +5:30      |
| Afghanistan Time (AFT)    | +4:30      |
| Myanmar Time (MMT)        | +6:30      |
| Nepal Time (NPT)          | +5:45      |
| Chatham Islands (CHAST)   | +12:45     |
| Marquesas Islands (MART)  | -9:30      |

Because hourly buckets are aligned to whole-hour UTC boundaries, a single local hour in these timezones will always straddle two hourly buckets. To get complete data for any given local hour, you must query **2 consecutive hours**.

### Example: Querying for 2:00 PM IST

IST is UTC+5:30, so 2:00 PM IST = 08:30 UTC. The hour from 2:00 PM to 3:00 PM IST (08:30 - 09:30 UTC) spans two UTC hour buckets:

* **08:00 - 08:59 UTC** (contains the first 30 minutes: 2:00 PM - 2:30 PM IST)
* **09:00 - 09:59 UTC** (contains the last 30 minutes: 2:30 PM - 3:00 PM IST)

To retrieve the full hour, query both buckets:

```json theme={null}
{
  "start_date": "2025-01-15T08:00:00Z",
  "end_date": "2025-01-15T09:59:59Z"
}
```

<Warning>
  This applies when querying at **hour-level granularity** via `/v2/reports/*`. If you are in a fractional-offset timezone and request data by hour, always request 2 consecutive hours to avoid missing data that falls in the adjacent bucket.
</Warning>

## Troubleshooting

### Missing data at day boundaries

**Problem:** You're querying January 1st but missing the first or last few hours.

**Solution:** Make sure you're not using the `Z` suffix. Use `"start_date": "2025-01-01"` instead of `"start_date": "2025-01-01T00:00:00Z"`.

### Data from previous/next day appearing

**Problem:** Your daily query includes data from adjacent days.

**Solution:** You're likely using `Z` suffix with midnight UTC, which doesn't align with EST days. Remove the timezone suffix.

### Unexpected DST behavior

**Problem:** Your queries have a 1-hour difference during DST transitions.

**Solution:** Let the API handle DST automatically by using dates without timezone. If you must use UTC, remember the offset changes between EST (-5) and EDT (-4).

## Future Changes

<Note>
  In a future version of the API, we plan to support full ISO 8601 timezone offsets (e.g., `-05:00`, `+09:00`) to enable multi-timezone queries. Dates without timezone specification will be deprecated at that time.
</Note>

For now, the recommended approach is to use dates without timezone and let the API handle the EST conversion for you.