Reference

Read API reference

Read your project’s analytics from a server, a warehouse job or a BI tool. The endpoints below are generated from the API’s own OpenAPI document.

Base URL and authentication

Every endpoint is under https://stg.webmetric.io/v1. Create a read key in Settings and send it as a bearer token in the Authorization header. A read key belongs to one project, is shown once, and can be revoked at any time.

RequestShell

curl "https://stg.webmetric.io/v1/read/projects/your_project_id/summary?range=7d" \
  -H "Authorization: Bearer wm_r_your_read_key"

Read keys are secret. Call the API from your own server, and never put a read key in page source or in a browser.

The read API is included on some plans only, as listed under Plans. On other plans every call answers 402.

Rate limits

Each key has its own bucket of requests, which refills continuously. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit the answer is 429, with Retry-After giving the seconds to wait.

Windows, filters and pages

range is a preset window ending now. from and to take dates in the project’s time zone, or ISO 8601 date-times. A window reaching further back than the project keeps data is refused with range_exceeds_retention.
Every dimension is also a filter, such as device=mobile. Add device_op=is_not to invert it.
List endpoints return data and next_cursor. Pass next_cursor back as cursor until it is null.

Date window

Date window
Parameter	Type	Description
`range`query	`string`	A preset window ending now. The default is 7d, shortened to the project’s retention.`24h7d30d90d`
`from`query	`string`	A date (YYYY-MM-DD) in the project’s time zone, or an ISO 8601 date-time with an offset. Needs to.
`to`query	`string`	Inclusive when a date. Must be after from. A date beyond the project’s retention is refused.

Filters

devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content

Each filter takes a value. A second parameter with the same name plus _op, such as device_op, says how the value is compared. Without it the value must match exactly.

Operators:isis_notcontainsnot_contains

Filters
Parameter	Type	Description
`goal`query	`uuid`	Only visitors who completed this goal.

Pagination

Pagination
Parameter	Type	Description
`limit`query	`integer` from 1 to 1000	Rows per page, from 1 to 1000. The default is 100.
`cursor`query	`string`	The next_cursor from the previous page.

Endpoints

Generated from the API’s OpenAPI document, version 1.0.0: 11 endpoints.

Totals for the window, with the previous window for comparison

GET/v1/read/projects/{id}/summary

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters

Response fields
Field	Type	Description
`pageviews`	`integer`
`sessions`	`integer`
`visitors`	`integer`
`avgDurationSeconds`	`integer`
`bounceRate`	`number` from 0 to 1
`from`	`string`	Start of the window, ISO 8601 in UTC, inclusive.
`to`	`string`	End of the window, ISO 8601 in UTC, exclusive.
`previous`	`object` or null	The window of the same length just before this one. Null when it had no sessions.
`previous.pageviews`	`integer`
`previous.sessions`	`integer`
`previous.visitors`	`integer`
`previous.avgDurationSeconds`	`integer`
`previous.bounceRate`	`number` from 0 to 1

Page views, visitors and sessions per hour or day, empty buckets included

GET/v1/read/projects/{id}/timeseries

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters

Response fields
Field	Type	Description
`from`	`string`
`to`	`string`
`timezone`	`string`	The project’s IANA time zone. Buckets start at local midnight, or on the hour, in it.
`bucket`	`string`	`hourdayweek`
`data`	`object[]`
`data[].bucket`	`string`	The bucket’s start as ISO 8601 with the offset of the project’s time zone, such as 2026-09-27T00:00:00+02:00.
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`data[].sessions`	`integer`

Pages by page views

GET/v1/read/projects/{id}/top-paths

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

Visitors and page views by one dimension

GET/v1/read/projects/{id}/breakdown

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.
`by`query, required	`string`	`devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content`

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].label`	`string`	The dimension’s value. Empty for none, such as a visit with no referrer.
`data[].country`	`string`	By region or city only: the ISO 3166-1 alpha-2 country the row belongs to.
`data[].visitors`	`integer`
`data[].pageviews`	`integer`
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

Custom events with counts and conversion rate

GET/v1/read/projects/{id}/events

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].name`	`string`
`data[].count`	`integer`
`data[].visitors`	`integer`
`data[].conversionRate`	`number` from 0 to 1	Visitors who sent the event, over all visitors.
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

Pages visits started on

GET/v1/read/projects/{id}/entry-pages

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].sessions`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

Pages visits ended on, with exit rate

GET/v1/read/projects/{id}/exit-pages

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].exits`	`integer`
`data[].pageviews`	`integer`
`data[].exitRate`	`number` from 0 to 1	Exits over page views of the path.
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

The project’s funnels

GET/v1/read/projects/{id}/funnels

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].id`	`uuid`
`data[].name`	`string`
`data[].steps`	`object[]`
`data[].windowHours`	`integer`
`data[].createdAt`	`string`
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

How many sessions reached each step

GET/v1/read/projects/{id}/funnels/{funnelId}/report

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.
`funnelId`path, required	`uuid`

Also takes: Date window, Filters

Response fields
Field	Type	Description
`name`	`string`
`windowHours`	`integer`
`conversionRate`	`number` from 0 to 1
`steps`	`object[]`
`steps[].label`	`string`
`steps[].entered`	`integer`
`steps[].ofStart`	`number` from 0 to 1
`steps[].ofPrevious`	`number` from 0 to 1
`steps[].droppedOff`	`integer`

Conversions for each goal

GET/v1/read/projects/{id}/goals

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.

Also takes: Date window, Filters, Pagination

Response fields
Field	Type	Description
`data`	`object[]`
`data[].id`	`uuid`
`data[].name`	`string`
`data[].kind`	`string`	`patheventclick`
`data[].match`	`string`	`exactcontainsstarts_with`
`data[].value`	`string`
`data[].conversions`	`integer`
`data[].converters`	`integer`
`data[].conversionRate`	`number` from 0 to 1
`next_cursor`	`string` or null	Pass as cursor for the next page. Null on the last page.

A whole dataset as CSV, never truncated

GET/v1/read/projects/{id}/export

Parameters
Parameter	Type	Description
`id`path, required	`uuid`	The project the read key belongs to.
`dataset`query	`string`	`pathspagestimeseriescustom-eventsentry-pagesexit-pagesdevicesbrowsersoscountriesregionscitiesreferrerschannelsutm-sourcesutm-mediumsutm-campaigns`

Also takes: Date window, Filters

Answers with a CSV file that starts with a header row.

Errors

An error answers with JSON holding a stable code and a message. Branch on the code: the message can change.

Error responses
Status	Codes	Description
`400`	`invalid_payloadinvalid_rangerange_exceeds_retentioninvalid_cursor`	The request is not valid: a parameter, the window or the cursor.
`401`	`unauthenticatedunknown_keykey_revoked`	The key is missing, unknown or revoked.
`402`	`upgrade_required`	The organization’s plan does not include the read API.
`404`	`not_found`	The project is not the key’s, or the resource does not exist.
`429`	`rate_limited`	Too many requests. Wait for the seconds in Retry-After.

The OpenAPI document

The machine-readable document is at https://stg.webmetric.io/v1/openapi.json. Import it into an API client, or generate a typed client from it.