Show search and navigation.

 

Generate Report

Generate report data.

Key information:

Request

Generate a report via the following request:

HTTP Method Request URI

POST

https://api.vdms.io/report-builder/v1/reports

Request Headers

This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.

Unlike requests to api.edgecast.com, requests to our API gateway (api.vdms.io) require an access token (OAuth).

Request Body

Pass the following request body parameters:

Name Data Type Description

query

Required

Object

Defines how report data will be generated.

delivery

Object

Determines whether report data will be delivered via email or included in the response.

  • Email: If you include this optional parameter, then our service will deliver report data via email upon successfully generating your report. The response to a successful request will be a 202 Accepted.

  • Response Body: If you do not specify this optional parameter, then our service will provide report data within the items array of the response for this endpoint when the status response property returns completed.

    Use the Get Report endpoint to find out a report's status and to retrieve report data.

query Object

The query object contains the following property:

Name Data Type Description

params

Object

Contains a configuration for report data generation and delivery.
params Object

The params object contains the following properties:

Name Data Type Description

by

String

Identifies a granularity by its system-defined ID.

Use the Get All Granularities endpoint to retrieve a list of available granularities and their system-defined IDs.

Due to our data retention policy, the set of available granularities varies according to the age of the data being requested. Pass the start and end query string parameters when requesting the Get All Granularities endpoint to find out the set of supported granularities for that time range.

dimensions

Object

Contains a string value for each dimension that will be included in the report.

Use the Get All Dimensions endpoint to retrieve a list of dimensions and their system-defined IDs.

end

Required

String

Required for the params Object

Determines the report's relative or fixed end date/time.

Time is only relevant for reports that only contain data that occurred within the last 7 days and whose time interval is set to 5 minutes or hourly.

ClosedLearn more on how time intervals affect reporting.

Data is reported in buckets. The duration of the bucket is determined by either one of the following:

  • by property: If the by property has been defined, then the time interval (i.e., granularity) assigned to it determines the bucket's duration.

    Learn more about time intervals.

    Example:

    If the report's time interval is weekly, then each data bucket starts on Monday at 12:00:00 AM (UTC) and ends on Monday of the following week at 12:00:00 AM (UTC).

  • Default: If the by property has not been defined, then the age of the report determines the duration of each bucket. If the report only contains data that occurred within the last 7 days, then data is reported in 5 minute buckets. If the report contains data that occurred over 7 days ago, then data is reported in daily buckets.

If a report's start or end timestamp falls in the middle of a bucket, then the report will include all of the data contained by that bucket.

Example:

A report is configured as follows:

  • Time Interval: Weekly
  • Start Timestamp: Friday (2/7) at 5:00 PM PST
  • End Timestamp: The following Wednesday (2/12) at 9:00 AM PST

Based off of the above configuration, the report's actual date range will be:

  • Start Timestamp: Monday (2/3) at 12:00:00 AM (UTC)
  • End Timestamp: Monday (2/17) at 12:00:00 AM (UTC)
ClosedLearn more about relative dates.

The available relative date keywords are:

Keyword Description

now

Identifies the date and time (UTC) when the request was submitted.

start_day

Identifies 00:00:00 (UTC) on the day when the request was submitted.

start_week

Identifies 00:00:00 (UTC) on Monday of the week when the request was submitted.

start_month

Identifies 00:00:00 (UTC) on the 1st of the month when the request was submitted.

start_year

Identifies 00:00:00 (UTC) on January 1 of the year when the request was submitted.

The available time units are:

Keyword Description

y

Year

M

Month

w

Week

d

Day

h

Hour

m

Minute

s

Second

Examples

Sample dates are described below.

Value Description

2024-01-01T00:00:00Z

Identifies the start of 2024 (UTC).

now-1h

Identifies exactly 60 minutes before the request was submitted.

start_day-7d

Identifies a date that is 7 days prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/1/2024 at 00:00:00 UTC

start_month-1d

Identifies the last day of the month prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2020 at 1:00:00 P.M. PST

Relative date/time:

12/31/2019 at 00:00:00 UTC

start_year+1d

Identifies the second day of the year on which the request was submitted at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/2/2024 at 00:00:00 UTC

Fixed Date Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

filter

String

Contains a list of filters for the data that will be generated for this report.

Key information:

  • Set this property by converting an array of objects into a string value. Each object in this array represents a filter. Each object contains the following properties:

    • field: A string that identifies a dimension by its system-defined ID. Report data will be filtered by this dimension.

      Use the Get All Dimensions endpoint to retrieve a list of dimensions and their system-defined IDs.

    • operator: A string that identifies a comparison operator by its system-defined ID. This comparison operator establishes the relationship between field and value that report data must meet.

      Use the Get All Operators endpoint to retrieve a list of comparison operators and their system-defined IDs.

    • value: A string, number, or array that indicates the value to which the comparison operator will be applied. The data type for this property is determined by the comparison operator's multi_value property and the dimension's field_type property.

  • Example:

    The following configuration filters by delivery platform:

    Property Value

    field

    String

    platform

    operator

    String

    in

    value

    Array of String Values

    Valid values are:

    • cache: HTTP Large
    • wac: HTTP Small
    • adn:ADN

    The following code excerpt filters by the ADN delivery platform:

    "filter": "[{\"field\":\"platform\",\"operator\":\"in\",\"value\":[\"adn\"]}]",

limit

Required

Integer

Required for the params Object

Determines the maximum number of rows that may be included in a report. Valid values are:

1 - 30000

metrics

Required

Array of String Values

Required for the params Object

Identifies one or more metrics that will be included in the report. Specify each metric as a string value.

Use the Get All Metrics endpoint to retrieve a list of metrics and their system-defined IDs.

sort

Array of String Values

Determines how report data will be sorted.

Key information:

  • Sort report data by dimensions or metrics.

  • Perform a reverse sort by prepending -.

    Example:

    Sort report data by number of requests in descending order.

    ["-request_count"]
  • If a second metric or dimension is defined, then report data will be sorted by the first field. The second field determines how records with the same value will be sorted.

start

Required

String

Required for the params Object

Determines the report's relative or fixed start date/time.

ClosedLearn more about relative dates.

The available relative date keywords are:

Keyword Description

now

Identifies the date and time (UTC) when the request was submitted.

start_day

Identifies 00:00:00 (UTC) on the day when the request was submitted.

start_week

Identifies 00:00:00 (UTC) on Monday of the week when the request was submitted.

start_month

Identifies 00:00:00 (UTC) on the 1st of the month when the request was submitted.

start_year

Identifies 00:00:00 (UTC) on January 1 of the year when the request was submitted.

The available time units are:

Keyword Description

y

Year

M

Month

w

Week

d

Day

h

Hour

m

Minute

s

Second

Examples

Sample dates are described below.

Value Description

2024-01-01T00:00:00Z

Identifies the start of 2024 (UTC).

now-1h

Identifies exactly 60 minutes before the request was submitted.

start_day-7d

Identifies a date that is 7 days prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/1/2024 at 00:00:00 UTC

start_month-1d

Identifies the last day of the month prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2020 at 1:00:00 P.M. PST

Relative date/time:

12/31/2019 at 00:00:00 UTC

start_year+1d

Identifies the second day of the year on which the request was submitted at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/2/2024 at 00:00:00 UTC

Fixed Date Format:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

units

Object

Indicates unit information for each metric defined by the metrics property. This information is reported as a key-value pair with the following syntax:

"Metric" : "Units"
ClosedTo identify the set of available units of measurements
  1. Request the Get All Metrics endpoint.
  2. Examine the response to find the desired metric. Look at the value assigned to the unit property.
  3. Request the Get All Units endpoint.
  4. Find all units of measurements whose unit property is set to a matching value.

Example:

The total_time metric's unit property is set to time. The following units of measurement have a unit property set to time:

day | hour | minute | second

This means that total_time may be reported using any of the above units of measurements. The following sample configuration reports total_time in minutes.

...
	"units": {
		"total_time" : "minute"
	}
...

Do not provide unit information for metrics that report percentages.

Default Value:

If a unit of measurement is not assigned to a metric, then it will be assigned one that has a matching type and whose scale property is set to 1. Use the Get All Units endpoint to view the type and scale for each unit of measurement.

delivery Object

The delivery object contains the following properties:

Name Data Type Description

format

String

Determines whether report data will be formatted as CSV or JSON. Valid values are:

csv | json

method

String

Set it to email.

properties

Object

Contains settings that define email delivery.

body

String

Contains the body of the email.

filename

String

Defines the report's base file name. The report's start and end date/time is appended to this name.

Syntax:

Base File Name_Start Date/TimeThe report's start date/time is calculated during report generation according to the report's date range._End Date/TimeThe report's end date/time is calculated during report generation according to the report's date range..Format Type.zip

Date/Time Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

subject

String

Contains the email's base subject line. The report's start and end date/time is appended to this subject line.

Syntax:

Base Subject LineStart Date/TimeThe report's start date/time is calculated during report generation according to the report's date range. - End Date/TimeThe report's end date/time is calculated during report generation according to the report's date range.

Date/Time Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

to

String

Identifies one or more recipients by their email address. Use a comma to delimit multiple email addresses. Each specified email address must correspond to a user within your MCC account.

Response

The response to the above request includes an HTTP status code, response headers, and a response body.

Status Code

A status code indicates whether the request was successfully performed.

Response Headers

The response for this endpoint only includes standard HTTP response headers.

View common response headers.

Response Body

The response body for a successful request contains the following response elements:

Name Data Type Description
@id String Indicates the relative path to an endpoint through which you may retrieve the current report.

@type

String

Returns Report.

completed_at

String

Indicates the timestamp (UTC) at which report data generation completed.

Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

created_at

String

Indicates the timestamp (UTC) at which report data was requested.

Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

dimensions

Array of String Values

Indicates the report's actual dimensions.

Time is automatically reported when a time interval has been defined. If the report query's configuration defines the by property, then the time dimension, if not already present, will be added to this property's value. If this occurs, then this property will not match the dimensions property in the query object.

id

String

Identifies this report by its system-defined ID.

items

Array of Objects

Contains report data. Each object, which represents a recordA record contains report data that identifies each unique combination of dimensions. in the report, contains key-value pairs that correspond to the set of fields reported by the metrics and dimensions properties.

Report data is only returned when the status property is set to completed.

A record will only be included within a report when at least one metric is set to a non-zero value. Missing records is not an indicator of data loss.

If a time interval has been defined via the by property, then the Time dimension will be automatically included in the report. This occurs regardless of whether it was defined in the report query.

metrics

Array of String Values

Indicates the report's metrics.

query

Object

Contains the query used to generate report data.

status

String

Indicates the current status for the request to generate report data. Valid values are:

submitted | processing | error | canceled | completed
query Object

The query object describes the query used to generate report data via the following properties:

Name Data Type Description

params

Object

Defines the query for the data generated in the current report.
params Object

The params object contains the following properties:

Name Data Type Description

by

String

Identifies a granularity by its system-defined ID.

Use the Get All Granularities endpoint to retrieve a list of available granularities and their system-defined IDs.

dimensions

Object

Contains a string value for each dimension assigned to this report.

Use the Get All Dimensions endpoint to retrieve a list of dimensions and their system-defined IDs.

end

String

Determines the report's relative or fixed end date/time.

Time is only relevant for reports that only contain data that occurred within the last 7 days and whose time interval is set to 5 minutes or hourly.

ClosedLearn more on how time intervals affect reporting.

Data is reported in buckets. The duration of the bucket is determined by either one of the following:

  • by property: If the by property has been defined, then the time interval (i.e., granularity) assigned to it determines the bucket's duration.

    Learn more about time intervals.

    Example:

    If the report's time interval is weekly, then each data bucket starts on Monday at 12:00:00 AM (UTC) and ends on Monday of the following week at 12:00:00 AM (UTC).

  • Default: If the by property has not been defined, then the age of the report determines the duration of each bucket. If the report only contains data that occurred within the last 7 days, then data is reported in 5 minute buckets. If the report contains data that occurred over 7 days ago, then data is reported in daily buckets.

If a report's start or end timestamp falls in the middle of a bucket, then the report will include all of the data contained by that bucket.

Example:

A report is configured as follows:

  • Time Interval: Weekly
  • Start Timestamp: Friday (2/7) at 5:00 PM PST
  • End Timestamp: The following Wednesday (2/12) at 9:00 AM PST

Based off of the above configuration, the report's actual date range will be:

  • Start Timestamp: Monday (2/3) at 12:00:00 AM (UTC)
  • End Timestamp: Monday (2/17) at 12:00:00 AM (UTC)
ClosedLearn more about relative dates.

The available relative date keywords are:

Keyword Description

now

Identifies the date and time (UTC) when the request was submitted.

start_day

Identifies 00:00:00 (UTC) on the day when the request was submitted.

start_week

Identifies 00:00:00 (UTC) on Monday of the week when the request was submitted.

start_month

Identifies 00:00:00 (UTC) on the 1st of the month when the request was submitted.

start_year

Identifies 00:00:00 (UTC) on January 1 of the year when the request was submitted.

The available time units are:

Keyword Description

y

Year

M

Month

w

Week

d

Day

h

Hour

m

Minute

s

Second

Examples

Sample dates are described below.

Value Description

2024-01-01T00:00:00Z

Identifies the start of 2024 (UTC).

now-1h

Identifies exactly 60 minutes before the request was submitted.

start_day-7d

Identifies a date that is 7 days prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/1/2024 at 00:00:00 UTC

start_month-1d

Identifies the last day of the month prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2020 at 1:00:00 P.M. PST

Relative date/time:

12/31/2019 at 00:00:00 UTC

start_year+1d

Identifies the second day of the year on which the request was submitted at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/2/2024 at 00:00:00 UTC

Fixed Date Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

filter

String

Contains a list of filters.

Key information:

  • This property is an array of objects expressed as a string value. Each object in this array represents a filter. Each object contains the following properties:

    • field: A string that identifies a dimension by its system-defined ID. Report data will be filtered by this dimension.

      Use the Get All Dimensions endpoint to retrieve a list of dimensions and their system-defined IDs.

    • operator: A string that identifies a comparison operator by its system-defined ID. This comparison operator establishes the relationship between field and value that report data must meet.

      Use the Get All Operators endpoint to retrieve a list of comparison operators and their system-defined IDs.

    • value: A string, number, or array that indicates the value to which the comparison operator will be applied. The data type for this property is determined by the comparison operator's multi_value property and the dimension's field_type property.

  • Example:

    The following configuration filters by delivery platform:

    Property Value

    field

    String

    platform

    operator

    String

    in

    value

    Array of String Values

    Valid values are:

    • cache: HTTP Large
    • wac: HTTP Small
    • adn: ADN

    The following code excerpt filters by the ADN delivery platform:

    "filter": "[{\"field\":\"platform\",\"operator\":\"in\",\"value\":[\"adn\"]}]",

limit

Integer

Determines the maximum number of rows that may be included in a report. Valid values are:

1 - 30000

metrics

Array of String Values

Identifies one or more metrics that will be included when report data is generated from this report.

Use the Get All Metrics endpoint to retrieve a list of metrics and their system-defined IDs.

sort

Array of String Values

Determines how report data will be sorted.

Key information:

  • Sort report data by dimensions or metrics.

  • Perform a reverse sort by prepending -.

    Example:

    Sort report data by number of requests in descending order.

    ["-request_count"]
  • The first string value in the array determines how records will be sorted. Additional string values determine sort order for records with the same value.

start

String

Determines the report's relative or fixed start date/time.

Time is only relevant for reports that only contain data that occurred within the last 7 days and whose time interval is set to 5 minutes or hourly.

ClosedLearn more on how time intervals affect reporting.

Data is reported in buckets. The duration of the bucket is determined by either one of the following:

  • by property: If the by property has been defined, then the time interval (i.e., granularity) assigned to it determines the bucket's duration.

    Learn more about time intervals.

    Example:

    If the report's time interval is weekly, then each data bucket starts on Monday at 12:00:00 AM (UTC) and ends on Monday of the following week at 12:00:00 AM (UTC).

  • Default: If the by property has not been defined, then the age of the report determines the duration of each bucket. If the report only contains data that occurred within the last 7 days, then data is reported in 5 minute buckets. If the report contains data that occurred over 7 days ago, then data is reported in daily buckets.

If a report's start or end timestamp falls in the middle of a bucket, then the report will include all of the data contained by that bucket.

Example:

A report is configured as follows:

  • Time Interval: Weekly
  • Start Timestamp: Friday (2/7) at 5:00 PM PST
  • End Timestamp: The following Wednesday (2/12) at 9:00 AM PST

Based off of the above configuration, the report's actual date range will be:

  • Start Timestamp: Monday (2/3) at 12:00:00 AM (UTC)
  • End Timestamp: Monday (2/17) at 12:00:00 AM (UTC)
ClosedLearn more about relative dates.

The available relative date keywords are:

Keyword Description

now

Identifies the date and time (UTC) when the request was submitted.

start_day

Identifies 00:00:00 (UTC) on the day when the request was submitted.

start_week

Identifies 00:00:00 (UTC) on Monday of the week when the request was submitted.

start_month

Identifies 00:00:00 (UTC) on the 1st of the month when the request was submitted.

start_year

Identifies 00:00:00 (UTC) on January 1 of the year when the request was submitted.

The available time units are:

Keyword Description

y

Year

M

Month

w

Week

d

Day

h

Hour

m

Minute

s

Second

Examples

Sample dates are described below.

Value Description

2024-01-01T00:00:00Z

Identifies the start of 2024 (UTC).

now-1h

Identifies exactly 60 minutes before the request was submitted.

start_day-7d

Identifies a date that is 7 days prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/1/2024 at 00:00:00 UTC

start_month-1d

Identifies the last day of the month prior to the request at 00:00:00 (UTC).

Sample request timestamp:

1/8/2020 at 1:00:00 P.M. PST

Relative date/time:

12/31/2019 at 00:00:00 UTC

start_year+1d

Identifies the second day of the year on which the request was submitted at 00:00:00 (UTC).

Sample request timestamp:

1/8/2024 at 1:00:00 P.M. PST

Relative date/time:

1/2/2024 at 00:00:00 UTC

Fixed Date Format:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

units

Object

Indicates unit information for each metric defined in the report. This information is reported as a key-value pair with the following syntax:

"Metric" : "Units"

Use the Get All Units endpoint to retrieve a list of units of measurements and their system-defined IDs.

Unit information is not provided for metrics that report percentages.

Errors

The response body for an unsuccessful request will contain an error response that provides additional information.

Sample Request and Response

A sample JSON request is shown below.

POST https://api.vdms.io/report-builder/v1/reports HTTP/1.1

Authorization: Bearer A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01z...A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01zOTIzQjI1MTYzRjU4MU1wQ0I3MUNBRDk3QjAzNkUwQjgiLCJ01XAiOiJKV1QiLCJ4NXQiOiJGMDc4bzVJN0pSWV9XQm9Ndcc5dGw3QTI0TGcifQ.1yJuYmYiOj11NjUzMDgwNzgsImV4cCI6MTU2NTMwODM3OCwiaXNzIjoiacR0ccM6Ly9pZC52ZG1zLmlvIiwiYXVkIjpbImc0dcBzOi8vaWQudmRtcy5pby9yZXNvdXJjZXMiLCJlYy5ydWxlcyJdLCJjbGllbnRfaWQiOiIxNTccOWZmZi04MTQzLTRmOW1tOWY1Yi1jNDgzZWVkNzclM2QiLCJzY29wZSI6WyJlYy5ydWxlcyJdfQ.XQ4TvzDrwLo4bO71cb1TbgYxmtcgTzC46Do0A9F3inAqw1qcr_Nr9IgRDxJDqR4Udc9QR86LVTQC2-ogGWP3pI12GtDtiUQdKYs5fpcuMf2Kbqau6kuU1M5BJm_GOcBNCCAJnU7SrDprVbPlwanGqk3yjcyo9nto8KWCRTwq2t31UQ1Ci31FZSr4vaMZJqk1vBW6NS3-yGowGCZbSIQBKpSgcc75coPtSjF1Qi6M4yORDyMC8c3KKlIp2b-6mpfDFXINIFV-XvnNuQ9v-lcc43_VWuDA_cQO8wmS4VzS1Ac1tpg1Pp4Bcdtjt12yKAXvi0X19R1BDmpxmO17cRRKYQ

Accept: application/json

Content-Type: application/json

Host: api.vdms.io

Content-Length: 253

{
	"query": {
		"params": {
			"by": null,
			"end": "now",
			"limit": 5000,
			"metrics": [
				"file_size"
			],
			"sort": [
				"-file_size"
			],
			"start": "start_day-7d",
			"units": {
				"file_size": "megabyte"
			}
		}
	}
}

A sample JSON response for a completed report is shown below.

HTTP/1.1 200 OK

Cache-Control: no-cache

Content-Type: application/json; charset=utf-8

Date: Thu, 15 Apr 2021 12:00:00 GMT

Content-Length: 577

{
	"@id": "/report-builder/v1/reports/24571caae75e2a69f2f4bf8a",
	"@type": "Report",
	"completed_at": "2020-02-27T01:34:36.392000Z",
	"created_at": "2020-02-27T01:34:34.655000Z",
	"dimensions": [],
	"id": "24571caae75e2a69f2f4bf8a",
	"items": [{
			"file_size": 57.15
		}
	],
	"metrics": ["file_size"],
	"query": {
		"params": {
			"end": "2020-02-27T01:34:34Z",
			"limit": 5000,
			"metrics": ["file_size"],
			"sort": ["-file_size"],
			"start": "2020-02-20T00:00:00Z",
			"units": {
				"file_size": "terabyte"
			}
		}
	},
	"status": "completed"
}

A sample JSON response for a report that is still being processed is shown below.

HTTP/1.1 202 Accepted

Cache-Control: no-cache

Content-Type: application/json; charset=utf-8

Date: Thu, 15 Apr 2021 12:00:00 GMT

Content-Length: 496

{
	"@id": "/report-builder/v1/reports/24571caae75e2a69f2f4bf8a",
	"@type": "Report",
	"created_at": "2020-02-27T01:34:34.655000Z",
	"dimensions": [],
	"id": "24571caae75e2a69f2f4bf8a",
	"items": [],
	"metrics": ["file_size"],
	"query": {
		"params": {
			"end": "2020-02-27T01:34:34Z",
			"limit": 5000,
			"metrics": ["file_size"],
			"sort": ["-file_size"],
			"start": "2020-02-20T00:00:00Z",
			"units": {
				"file_size": "terabyte"
			}
		}
	},
	"status": "submitted"
}