Time Range

 

Querieng Real-Time Metrics

  • Default time range is 5 minutes.

  • Time range to retrieve real-time metrics can only be up to 15 minutes long.

  • Start time cannot be farther than 15 minutes ago.

  • For real-time metrics endpoints, the ?days query parameter has been replaced by ?minutes.

  • For start_date and end_date, use the ISO 8601 date-time format. For example, YYYY-MM-DDTHH:mm:ssZ, YYYY-MM-DDTHH:mm:ss, YYYY-MM-DDTHH:mm:ss±HH:mm, and YYYY-MM-DD.

Query Examples for Real-Time Metrics

Assuming requests are sent on 2023-01-01 at 2:00 PM

Valid Query Invalid Query

?minutes=12

Time range <= 15 minutes

 ?days=100 days is unsupported for real-time metrics, and is replaced by minutes.

?start_date=2023-01-01T13:50:00Z&end_date=2023-01-01T14:10:00Z

Start timestamp is within the last 15 minutes

?start_date=2023-01-01T13:30:00Z&end_date=2023-01-01T14:00:00Z

Time range > 15 minutes

 

?start_date=2023-01-01T13:30:00Z&end_date=2023-01-01T13:40:00Z

Start timestamp is not within the last 15 minutes

 

Quering Historical Data

   

Number of Previous Days from Now

query parameter(s): days (integer; number of previous days from the most recent clock hour)

Example: ?days=5

If the current time is 2022-01-02T04:20:00Z, the API returns the historical metric data of the last 5 days from 2021-12-28T04:00:00Z through 2022-01-02T04:00:00Z at an hourly (PT1H) granularity. Here the end time is not exclusive and the last hourly data point is 2022-01-02T03:00:00Z.

Copy 
GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5
   

Start and End Date

query parameter(s): start_date and end_date, where the start_date is inclusive and end_date is exclusive.

See: ISO 8601 Date and Time Format.

Example:

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

The following request retrieves the historical metric data for a given time range start_date and end_date:

Copy 
GET https://api.conviva.com/insights/3.0/metrics/attempts?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T03:45:00Z
   

Start and End Epoch Time in Seconds

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

Example

?start_epoch=1641009600&end_epoch=1641095100

The following request retrieves the historical metric data for a given time range in terms of the epoch, starting at 1641009600 (that is, 2022-01-01T04:00:00.000Z) and ending at 1641095100 (that is, 2022-01-02T03:45:00.000Z):

Copy 
GET https://api.conviva.com/insights/3.0/metrics/attempts?start_epoch=1641009600&end_epoch=1641095100
   

Start and End Epoch Time in Milliseconds

query parameter(s): start_epoch_ms is inclusive and end_epoch_ms is exclusive (integer; Unix epoch time in seconds)

Example

?start_epoch=1641009600000&end_epoch=1641095135000

The following request retrieves the historical metric data for a given time range in terms of the epoch in milliseconds, starting at 1641009600000 (that is, 2022-01-01T04:00:00.000Z) and ending at 1641095135000 (that is, 2022-01-02T03:45:35.000Z):

Copy 
GET https://api.conviva.com/insights/3.0/metrics/attempts?start_epoch_ms=1641009600000&end_epoch_ms=1641095135000

When querying timeseries data, consider

  • the recency of the query time range

  • the length of the query time range

Limitations of Querying Historical Data

The APIs provide historical metric data for the last 13 months. However, the maximum length of a query time range per API request is 90 days. The API throws an HTTP 422 error if the input time range is beyond 90 days or the start date is not within the last 13 months (396 days).

Query Examples

Assuming requests are sent on 2023-01-01

Valid Query Invalid Query

?days=85

(i.e. time range of last 85 days) Time range <= 90 days

?days=100

Time range > 90 days

?start_date=2022-10-24&end_date=2022-12-25

Start timestamp is within the last 13 months

?start_date=2022-06-24&end_date=2022-12-25

Time range > 90 days

 

?start_date=2021-01-01&end_date=2022-12-25

Start timestamp is not within the last 13 months

Use of ISO 8601 Date Time Format

The API throws an HTTP 422 error if the date range is not specified according to the ISO 8601 date-time format.

Query Examples

Assuming requests are sent with start_date and end_date as per the ISO 8601 date-time format.

Valid Query Invalid Query

/insights/3.0/real-time-metrics/quality-summary/group-by/asset?start_date=2024-04-25T10:15:00Z&end_date=2024-04-25T10:20:00Z

Use the ISO 8601 date-time format YYYY-MM-DDTHH:mm:ssZ with the time zone designator (Z).

/insights/3.0/real-time-metrics/quality-summary/group-by/asset?start_date=4/25/2024 10:15 AM&end_date=4/25/2024 10:20 AM

Invalid start_date and end_date; The dates is not specified as per the ISO 8601 date-time format.

/insights/3.0/real-time-metrics/quality-summary/group-by/asset?start_date=2024-04-25T10:15:00&end_date=2024-04-25T10:20:00

Use the ISO 8601 date-time format YYYY-MM-DDTHH:mm:ss without the time zone designator (Z).

/insights/3.0/real-time-metrics/quality-summary/group-by/asset?start_date=2024-04-25&end_date=2024-04-26

The dates are mentioned following the ISO 8601 date format YYYY-MM-DD, but the range is more than the 15 minutes limit.

/insights/3.0/real-time-metrics/quality-summary/group-by/asset?start_date=2024-04-25T10:15:00-05:00&end_date=2024-04-25T10:20:00-05:00

Use the ISO 8601 date-time format YYYY-MM-DDTHH:mm:ss±HH:mm with a specific UTC offset.

  

 

API Metrics Time Range API Metrics Time Range API Metrics Time Range