Measurements¶

Reference for the measurements endpoints of the Surfmeter API.

Surfmeter API – Measurements v1¶

The Surfmeter API lets you manage clients, users, capabilities, measurements, and organization-wide settings programmatically.

Servers¶

Description	URL
https://surfmeter-server.{host}/client_admin_api/v1	https://surfmeter-server.{host}/client_admin_api/v1

Measurements¶

POST /measurements/search¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Request body

application/json

{
    "body": null,
    "source_only": true,
    "size": 0,
    "from": 0,
    "search_after": [
        null
    ],
    "scroll": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "description": "Request data for the measurements search action. Wraps an Elasticsearch search request against the current data owner's analytics index. The `body` property is passed through to Elasticsearch as a Query DSL payload; additional top-level properties (`size`, `from`, `search_after`, `scroll`) control pagination and streaming behavior and are forwarded to the Elasticsearch client alongside the body.",
    "type": "object",
    "additionalProperties": false,
    "required": [
        "body"
    ],
    "properties": {
        "body": {
            "additionalProperties": true,
            "description": "Elasticsearch Query DSL payload. Treated as a passthrough: any valid Elasticsearch search request body (`query`, `aggs`, `sort`, `size`, `from`, `search_after`, `_source`, etc.) is accepted. May also be provided as a JSON-formatted string, in which case it is parsed server-side.",
            "oneOf": [
                {
                    "type": "object"
                },
                {
                    "type": "string"
                }
            ]
        },
        "source_only": {
            "type": "boolean",
            "description": "If true, the response is reduced to a plain array of `_source` documents instead of the full Elasticsearch response envelope."
        },
        "size": {
            "type": "integer",
            "description": "Maximum number of hits to return. Forwarded to the Elasticsearch client as a top-level parameter; equivalent to setting `size` inside `body`."
        },
        "from": {
            "type": "integer",
            "description": "Offset of the first hit to return, used for basic pagination. Forwarded to the Elasticsearch client as a top-level parameter."
        },
        "search_after": {
            "type": "array",
            "description": "Opaque cursor for deep pagination. Pass the `sort` array from the last hit of the previous page; requires a stable `sort` clause in `body`.",
            "items": {}
        },
        "scroll": {
            "type": "string",
            "description": "Enables Elasticsearch scroll search with the given timeout (e.g. `\"1m\"`). When set, the response is streamed as NDJSON (`application/x-ndjson`) instead of a single JSON object."
        }
    }
}

Response 200 OK

application/json

Schema of the response body

{
    "description": "Response for the measurements search action. Shape depends on the request: when `source_only=true` the response is an array of measurement source documents; otherwise it is the raw Elasticsearch search response envelope (hits, aggregations, etc.). When `scroll` is set, results are streamed as NDJSON and this schema does not apply.",
    "oneOf": [
        {
            "description": "Returned when `source_only=true`: a plain array of measurement `_source` documents, without Elasticsearch metadata. Each item is a measurement document; its concrete shape depends on the measurement type (video, web, etc.).",
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": true
            }
        },
        {
            "description": "Default response: the Elasticsearch search response envelope. Only the outermost keys are described here; everything inside is passed through unchanged.",
            "type": "object",
            "additionalProperties": true,
            "properties": {
                "took": {
                    "type": "integer",
                    "description": "Time in milliseconds Elasticsearch spent executing the search."
                },
                "timed_out": {
                    "type": "boolean",
                    "description": "Whether the search timed out before completing."
                },
                "_shards": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Per-shard execution summary reported by Elasticsearch."
                },
                "hits": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Container for matching documents. Includes `total`, `max_score`, and `hits` (an array of hit objects with `_index`, `_id`, `_source`, `sort`, etc.)."
                },
                "aggregations": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Aggregation results, present only when the request `body` contained an `aggs` clause."
                },
                "_scroll_id": {
                    "type": "string",
                    "description": "Scroll cursor, present only when the request used the `scroll` parameter."
                }
            }
        }
    ]
}

GET /measurements/{id}¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
`id`	path	string		No

Response 200 OK

GET /measurements/{id}/p1203_client_report¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
`id`	path	string		No

Response 200 OK

GET /measurements/{id}/network_performance_report¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
`id`	path	string		No

Response 200 OK

Schemas¶

MeasurementSearchData¶

Name	Type
`body`
`from`	integer
`scroll`	string
`search_after`	Array<>
`size`	integer
`source_only`	boolean

MeasurementSearchResponse¶

Type:

Security schemes¶

Name	Type	Scheme	Description
ApiKeyAuth	apiKey		API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.