Sessions V3 API Time Range

Options to Select a Time Range Choose a time range for the Sessions V3 API using start and end dates, epoch seconds, epoch milliseconds, or number of previous days, subject to endpoint limitations.

Updated 2026-08-03 sessions-api-time-range

Options to Select a Time Range

Time Range

   

Start Date and End Date

query parameter(s): start_date and end_date (string; ISO 8601 date and time format)

  • start_date is inclusive

  • end_date is exclusive

Example ?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z

   

Start Epoch and End Epoch Time in Seconds

query parameter(s): start_epoch and end_epoch (integer; Unix epoch time in seconds)

  • start_epoch is inclusive

  • end_epoch is exclusive

Example ?start_epoch=1641009600&end_epoch=1641096000

   

Start Epoch and End Epoch Time in Milliseconds

query parameter(s): start_epoch_ms and end_epoch_ms (integer; Unix epoch time in milliseconds)

  • start_epoch_ms is inclusive

  • end_epoch_ms is exclusive

Example ?start_epoch_ms=1641009600000&end_epoch_ms=1641096000000

   

Number of Previous Days from Now

query parameter(s): days (integer; number of previous days from the time of request; only for GET /3.0/sessions/content/viewer)

Example ?days=1

If current time is 2022-01-02T04:20:59Z, the time range of ?days=1 is equivalent of 2022-01-01T04:20:59Z to 2022-01-02T04:20:59Z.

 

Limitations

When querying with a time range, consider the recency and length of the query time range.

Endpoints Limitations

GET /3.0/sessions/content

GET /3.0/sessions/ad

  • The query start timestamp must be within the last 31 days.

  • The maximum length of a query time range per API request is 3 hours.
GET /3.0/sessions/content/viewer

  • Normal accounts have access up to the most recent 30 days of viewer data.

  • Contact the account manager to access up to 90 days of viewer data.

The API throws an HTTP 422 error if the query time range is beyond the above limits.