API Resources¶

Common Parameters¶

These parameters can be used for any of the below resources.

Parameter	Value	Description
`start_time`	`string` (optional)	Define a start time in ISO-8601 format from which records will be queried. This applies to the `created_at` attribute of the record.
`end_time`	`string` (optional)	Define an end time in ISO-8601 format up until which records will be queried. This applies to the `created_at` attribute of the record.
`measurement_id`	`string` (optional)	A single measurement ID to query. Only for `measurements`, `client_reports`, `network_requests`, and `event_bundles` resources. Note: overrides all other parameters
`client_uuid`	`string` (optional)	Specify a client to query data from. Note: overrides any tags specified
`tags`	`array` of `string` (optional)	Filter by client's tags. If multiple tags are specified, all of them must be assigned to the client.
`label`	`string` (optional)	Filter by client's label.

Time Format¶

Valid formats for start_time and end_time are, e.g.:

2023-05-17T12:36:13.000Z
20230517T12:36:13
2023-05-17 12:36:13 UTC

Internally, the Time.parse method is used to parse the time strings, so any format that is supported by this method is valid.

Tags Format¶

Use tags[]=foo&tags[]=bar as syntax for specifying multiple tags. Alternatively, use tags=foo,bar (comma-separated). Use separate queries for OR-like tag combinations.

Resources¶

Measurements¶

Path: /measurements
Method: GET
Format: JSON

Gets a list of all measurements.

Return Value¶

An array of all measurements, where each measurement is an object, with optional nested objects. The schema for the data is available in our reference.

Parameters¶

Parameter	Value	Description
`type`	`VideoMeasurement`, `WebMeasurement`, `NetworkMeasurement`, `SpeedtestMeasurement` (optional)	Define a type of measurement to query.
`subject`	`array` of `string` (optional)	Filter measurements by their subject as defined in the public config.
`study_id`	`array` of `string` (optional)	Filter measurements by their study ID as defined in the public config.

Client Reports¶

Path: /client_reports
Method: GET
Format: JSON

Gets a list of all Client Reports.

Return Value¶

An array of all Client Reports, where each Client Report is an object, with optional nested objects. The schema for the data is available in our reference.

Parameters¶

Parameter	Value	Description
`type`	`string` (optional)	Define a type of Client Report to query. See the reference for a list of available types. Example: `IcmpPingClientReport`

Event Bundles¶

Path: /event_bundles
Method: GET
Format: JSON

Gets a list of all event bundles.

Return Value¶

An array of all event bundles, where each event bundle is an object, with optional nested objects. The schema for the data is available in our reference.

Note that the type of the event bundle must be passed as a parameter.

Parameters¶

Parameter	Value	Description
`type`	`VideoEventBundle`, `WebEventBundle`	Define a type of event bundle to query.

Network Requests¶

Path: /network_requests
Method: GET
Format: JSON

Gets a list of all network requests.

Return Value¶

An array of all network requests, where each network request is an object. The schema for the data is:

Property	Value	Description
`client_time`	`string` (ISO 8601)	The time the request was made, as reported by the client
`client_time_skewed`	`string` (ISO 8601)	The time the request was made, adjusted for any time skew
`data`	`object`	The actual request data, structure depends on the request type, see `requestWillBeSent`. Fields available: `requestId`, `loaderId`, `documentURL`, `timestamp`, `wallTime`, `type`, `frameId`, `request.url`, `request.method`, `request.headers`
`network_response`	`object`	The network response

Note that request data is pruned to save space. In particular, the following properties are not included:

request.mixedContentType
request.initialPriority
request.referrerPolicy
request.isSameSite
initiator
redirectHasExtraInfo
hasUserGesture

Each network response corresponds to the following schema:

Property	Value	Description
`client_time`	`string` (ISO 8601)	The time the response was received by the client
`client_time_skewed`	`string` (ISO 8601)	The time the response was received by the client, adjusted for any time skew
`data`	`object`	The actual response data, structure depends on the request type, see `responseReceived`. Fields available: `requestId`, `loaderId`, `timestamp`, `type`, `frameId`, and all from `response` except `securityState`, `securityDetails`, `alternateProtocolUsage`.

Again, note that response data is pruned to save space. We remove the following properties:

response.securityState
response.securityDetails
response.alternateProtocolUsage
hasExtraInfo

Clients¶

Path: /clients
Method: GET
Format: JSON

Gets a list of all clients.

Return Value¶

An array of all clients, where each client is an object, with optional nested objects. The schema for the data is:

Property	Value	Description
`uuid`	`string`	The client's UUID
`type`	`string`	The client's type
`label`	`string`	A label for the client (optional)
`created_at`	`string`	The date when the client was created
`updated_at`	`string`	The date when the client was updated
`disabled_at`	`string`	The date when the client was disabled (optional)
`disabled_reason`	`string`	The reason why the client was disabled (optional)
`tags`	`array` of `string`	The tags assigned to the client (optional)
`extra_label`	`string`	An extra label for the client (optional)
`registration_key`	Registration Key	The registration key for the client

Registration Key¶

Property	Value	Description
`registration_key`	`string`	The registration key for the client
`num_registrations_left`	`number`	The number of registrations left for the key. `-1` means unlimited uses

User Feedbacks¶

Path: /user_feedbacks
Method: GET
Format: JSON

Gets a list of all user feedbacks.

Return Value¶

An array of all user feedbacks, where each user feedback is an object. The schema for the data is:

Property	Value	Description
`id`	`number`	The unique identifier for the user feedback
`client`	`object`	The client associated with this feedback, with the object containing its `uuid`
`type`	`string`	The type of user feedback
`data_type`	`string`	The type of data stored in the feedback (typically "object")
`data`	`object`	The actual feedback data, structure depends on the feedback type
`client_time`	`string` (ISO 8601)	The time the feedback was submitted, as reported by the client
`client_time_skewed`	`string` (ISO 8601)	The adjusted client time, accounting for any time skew
`created_at`	`string` (ISO 8601)	The time the feedback was created in the database
`updated_at`	`string` (ISO 8601)	The time the feedback was last updated in the database

Note: The exact structure of the data object may vary depending on the specific type of user feedback.

Parameters¶

Parameter	Value	Description
`type`	`string` (optional)	Define a type of User Feedback to query. Available types depend on your specific application.

Search¶

Path: /search
Methods: GET, POST
Format: JSON or NDJSON (for streaming responses)

Provides direct search capabilities against the analytics data using Elasticsearch queries. For more details, see the Elasticsearch documentation.

Parameters¶

The following parameters are supported by our own API in addition to the ones supported by Elasticsearch:

Parameter	Value	Description
`body`	`object` or `string` (required)	The Elasticsearch query body. Can be provided as a JSON-formatted string or object when sent as a POST request with `Content-Type: application/json`. For details about the Query DSL, see the introduction or the Query DSL Reference.
`scroll`	`string` (optional)	Enable scrolling search with specified scroll timeout (e.g. "1m"). Returns results as streaming NDJSON. This corresponds to the `scroll` parameter in the Elasticsearch API.
`source_only`	`boolean` (optional)	If true, returns only the source documents without Elasticsearch metadata.

If you want to pass other parameters to the Elasticsearch API, you can do so by adding them to the object next to the body parameter, or as HTTP GET query parameters.

Return Value¶

The response format depends on the parameters:

Default: Returns the complete Elasticsearch response including metadata as JSON
With source_only=true: Returns an array of source documents only, skipping the Elasticsearch metadata
With scroll parameter: Streams results as NDJSON (one JSON document per line) with Content-Type: application/x-ndjson

Examples¶

A regular search query returning a single client's data:

POST /search
{
  "body": {
    "query": {
      "term": {
        "client_label.keyword": "my-custom-label"
      }
    }
  }
}

Note that for exact matches on text-based fields, you should use the .keyword suffix.

To perform an aggregation query, e.g. to aggregate statistic_values.initial_loading_delay by hour for the last 30 days, for video measurements only:

POST /search
{
  "body": {
    "size": 0,
    "query": {
      "bool": {
        "must": [
          {
            "range": {
              "created_at": {
                "gte": "now-30d/d",
                "lte": "now/d"
              }
            }
          },
          {
            "term": {
              "type.keyword": "VideoMeasurement"
            }
          }
        ]
      }
    },
    "aggs": {
      "loading_delay_over_time": {
        "date_histogram": {
          "field": "created_at",
          "calendar_interval": "hour"
        },
        "aggs": {
          "avg_loading_delay": {
            "avg": {
              "field": "statistic_values.initial_loading_delay"
            }
          }
        }
      }
    }
  }
}

You can perform a scrolling search (streaming response) for all data — the scroll parameter is required and gives the scroll timeframe:

POST /search?scroll=1m
{
  "body": {
    "query": {
      "match_all": {}
    }
  }
}

Searching with a simple Lucene query is also possible, while the size parameter limits the number of results returned:

POST /search?q=id:123
{ "body": { "size": 1 } }

ESQL¶

Path: /esql
Methods: GET, POST
Format: JSON

Provides direct query capabilities against the analytics data using Elasticsearch's ES|QL query language. For more details, see the ES|QL documentation.

Parameters¶

Parameter	Value	Description
`query`	`string` (required)	The ES

Return Value¶

Returns an array of documents matching the query criteria.

Security Constraints¶

The FROM clause in your query must reference indices that start with your index patterns, typically: analytics-production-<customer>* where <customer> is your customer's name
If using LOOKUP JOIN, the referenced indices must also be within your data owner's scope and must be known lookup indices
ENRICH clauses are allowed but currently not supported

Examples¶

Filtering records by a specific field:

POST /esql
{
  "query": "FROM analytics-production-<customer>* | WHERE type = \"VideoMeasurement\" | LIMIT 10"
}

Calculating average values with grouping:

POST /esql
{
  "query": "FROM analytics-production-<customer>* | WHERE type = \"VideoMeasurement\" | STATS avg_ild = avg(TO_DOUBLE(statistic_values.initial_loading_delay)) BY client_label | SORT client_label"
}