This page describes the options for date ranges that can be used in REST API calls.

Date range periods operate over the range 1970-01-01 to 2050-01-01. They are start
date and end date inclusive.

UI Label

Rolling

Type

Date/Preset

Start

End

Rounded

On

no

on

2017-01-15

2017-01-15T00:00:00Z

2017-01-15T23:59:59Z

no

Exactly

yes

on

-P3D

4.days.ago

3.days.ago

no

Before

no

before

2017-01-15

1970-01-01T00:00:00Z

2017-01-14T23:59:59Z

no

More than

yes

before

-P3D

1970-01-01T00:00:00Z

3.days.ago - 1.second

no

After

no

after

2017-01-15

2017-01-16T00:00:00Z

0.days.ago

yes*

Less than

yes

after

-P3D

3.days.ago

0.days.ago

no

Ever

no

preset

ever

1970-01-01T00:00:00Z

2050-01-01T00:00:00Z

no

Today

yes

preset

today

0.days.ago.beginning_of_day

1.day.from_now.beginning_of_day

yes

Yesterday

yes

preset

yesterday

1.day.ago.beginning_of_day

0.days.ago.beginning_of_day

yes

Last x days

yes

preset

last_x_days

x.days.ago.beginning_of_day

0.days.ago.beginning_of_day

yes

This month to date

yes

preset

this_month_to_date

0.days.ago.beginning_of_month

0.days.ago.beginning_of_day

yes

Between

no/no

between

2017-01-15/2017-01-16

2017-01-15T00:00:00Z

2017-01-16T23:59:59Z

yes*

N/A

no/yes

between

2017-01-15/-P2D

2017-01-15T00:00:00Z

2.days.ago

yes*

N/A

yes/no

between

-P2D/2017-01-16

2.days.ago

2017-01-16T23:59:59Z

yes*

Serializations

// "on"
{
  "type": "on",
  "date": "2017-01-15"
}

// "exactly"
{
  "type": "on",
  "date": "-P2D"
}

// "before"
{
  "type": "before",
  "date": "2017-01-15"
}

// "more than"
{
  "type": "before",
  "date": "-P2D"
}

// "after"
{
  "type": "after",
  "date": "2017-01-15"
}

// "less than"
{
  "type": "after",
  "date": "-P2D"
}

// "between" with two static dates
{
  "type": "between",
  "date": "2017-01-15/2017-01-16"
}

// "between" with two rolling dates
{
  "type": "between",
  "date": "-P5D/-PT48H"
}

// "between" with a static date and a rolling date
{
  "type": "between",
  "date": "2017-01-15/-P2D"
}

// "between" with a rolling date and a static date
{
  "type": "between",
  "date": "-P2D/2017-01-16"
}

// "between" with a future period
{
  "type": "between",
  "date": "-P5D/P4D"
}

// "last x days"
{
  "type": "preset",
  "preset": "last_7_days"
}

// "ever"
{
  "type": "preset",
  "preset": "ever"
}

// "today"
{
  "type": "preset",
  "preset": "today"
}

// "yesterday"
{
  "type": "preset",
  "preset": "yesterday"
}

// "this month to date"
{
  "type": "preset",
  "preset": "this_month_to_date"
}

Rolling Periods

Rolling date ranges change depending on the time they are run. A report run
at 2016-03-15T12:00:00Z with a range from 4 hours ago to now would effectively
be retrieving the range 2016-03-15T08:00:00Z to 2016-03-15T12:00:00Z, while the
same report run exactly 48 hours later would be querying over
2016-03-17T08:00:00Z to 2016-03-17T12:00:00Z. A static report's date range will
not change like this.

UI LabelTypeDate/PresetStartEndRounded
Exactlyon-P3D4.days.ago3.days.agono
More thanbefore-P3D1970-01-01T00:00:00Z3.days.ago - 1.secondno
Less thanafter-P3D3.days.ago0.days.agono
Rangebetween-P5D/-PT48H5.days.ago48.hours.agono
Todaypresettoday0.days.ago.beginning_of_day1.day.from_now.beginning_of_dayyes
Yesterdaypresetyesterday1.day.ago.beginning_of_day0.days.ago.beginning_of_dayyes
Last x dayspresetlast_x_daysx.days.ago.beginning_of_day0.days.ago.beginning_of_dayyes
This month to datepresetthis_month_to_date0.days.ago.beginning_of_month0.days.ago.beginning_of_dayyes

Exactly

The exactly option allows users to specify a rolling 24-hour period ending
some number of seconds ago. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60
sec/min = seconds ago or simply days ago
86400).

As an example, a user selecting "exactly 2 days ago" creates a rolling 24 hour
window from 72 hours ago to 48 hours ago.

This is serialized as:

{
  "date_range": {
    "type": "on",
    "date": "-P2D"
  }
}

More Than

The more than option allows users to specify an "unbounded", rolling period which
terminates a specified number of seconds ago. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60 sec/min = seconds ago or simply days ago 86400).

As an example, a user selecting "more than 2 days ago" creates a rolling window of time from 1970-01-01T00:00:00Z to 172,801 seconds ago.

This is serialized as:

{
  "date_range": {
    "type": "before",
    "date": "-P2D"
  }
}

Less Than

The less than option allows users to specify a rolling period bounded by a
specified number of seconds ago and the current time. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60 sec/min = seconds ago or simply days ago 86400).

As an example, a user selecting "less than 2 days ago" creates a rolling window of time from 172,799 seconds ago to 0 seconds ago.

This is serialized as:

{
  "date_range": {
    "type": "after",
    "date": "-P2D"
  }
}

Range

The between option allows users to specify two durations (or any combination of
durations and ISO8601 timestamps).

As an example, a user selecting "between 30-90 days ago"
creates a rolling period of time (-P90D/-P30D).

This is serialized as:

{
  "date_range": {
    "type": "between",
    "date": "-P90D/-P30D"
  }
}

Last X Days

The last X days preset allows users to specify a rolling period calendar-bounded by a
specified number of days ago and the end of yesterday.

As an example, a user selecting "last 7 days" creates a rolling window
of time from 7 days ago at the beginning of the day to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "last_7_days"
  }
}

Today

The today preset allows users to specify a rolling period calendar-bounded by the current day.

As an example, a user selecting "today" creates a rolling window
of time from 0 days ago at the beginning of the day to 0 days ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "today"
  }
}

Yesterday

The yesterday preset allows users to specify a rolling period calendar-bounded by the previous day.

As an example, a user selecting "yesterday" creates a rolling window
of time from 1 day ago at the beginning of the day to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "yesterday"
  }
}

This month to date

The this_month_to_date preset allows users to specify a rolling period calendar-bounded
by the beginning of the month and the current day.

As an example, a user selecting "this_month_to_date" creates a rolling window
of time from 0 days ago at the beginning of the month to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "this_month_to_date"
  }
}

Static Periods

Unlike rolling date ranges, static date ranges are not dependent on the time
they are run, and they do not change. The same report run two hours apart will
always query over the same timestamps.

UI LabelTypeDate/PresetStartEndRounded
Onon2017-01-152017-01-15T00:00:00Z2017-01-15T23:59:59Zno
Beforebefore2017-01-151970-01-01T00:00:00Z2017-01-14T23:59:59Zno
Afterafter2017-01-152017-01-16T00:00:00Z0.days.agoyes*
Everpresetever1970-01-01T00:00:00Z2050-01-01T00:00:00Zno
Betweenbetween2017-01-15/2017-01-162017-01-15T00:00:00Z2017-01-16T00:00:00Zno

On

The on option allows users to specify a date, which becomes a bounded, static
period between 00:00:00 and 23:59:59 for that calendar date. In the UI, users
select a calendar date, but internally, we use full ISO8601 timestamps for the
range.

As an example, a user selecting "on 2016-12-24" creates a static period of time
from 2016-12-24T00:00:00Z to 2016-12-24T23:59:59Z.

This is serialized as:

{
  "date_range": {
    "type": "on",
    "date": "2016-12-24"
  }
}

Before

The before option allows users to specify a date, which becomes a
bounded, static period starting on 01-01-1970 and terminating at 23:59:59 on the
day before the specified calendar date. In the UI, users select a calendar date,
but internally, we use full ISO8601 timestamps for the range.

As an example, a user selecting "before 2016-12-24" creates a static period of
time from 1970-01-01T00:00:00Z to 2016-12-23T23:59:59Z.

This is serialized as (note that end date is exclusive):

{
  "date_range": {
    "type": "before",
    "date": "2016-12-24"
  }
}

After

The after option allows users to specify a date, which becomes a bounded period
beginning at midnight on the day after the specified calendar date and terminating
at the current time.

If a date of the form YYYY-MM-DD is passed, the start date will be at 00:00:00 on
the following day. However, if a time is provided, the start date will be at that exact time.

As an example, a user selecting "after 2016-12-24" on 2017-12-30 creates a static period of
time from 2016-12-25T00:00:00 to 2017-12-30T00:00:00.

This is serialized as:

{
  "date_range": {
    "type": "after",
    "date": "2016-12-24"
  }
}

Between

The between option allows users to specify two dates, which become
the bounds of a static period starting at midnight on the start date and ending
at 23:59:59 on the end date (assuming no time is provided). In the UI, users select two calendar dates.

As an example, a user selecting "between 2016-12-24 and 2017-01-02"
creates a static period of time from 2016-12-24T00:00:00Z to
2017-01-02T23:59:59Z.

This is serialized as:

{
  "date_range": {
    "type": "between",
    "date": "2016-12-24/2017-01-02"
  }
}

Ever

The ever option is basically all time. It is represented internally as
1970-01-01T00:00:00Z to 2050-01-01T00:00:00Z.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "ever"
  }
}