Référence

Référence de l’API de lecture

Lisez les statistiques de votre projet depuis un serveur, une tâche d’entrepôt de données ou un outil de BI. Les points d’accès ci-dessous sont générés à partir du document OpenAPI de l’API elle-même.

URL de base et authentification

Chaque point d’accès se trouve sous https://stg.webmetric.io/v1. Créez une clé de lecture dans les Paramètres et envoyez-la comme jeton bearer dans l’en-tête Authorization. Une clé de lecture appartient à un seul projet, n’est affichée qu’une fois et peut être révoquée à tout moment.

RequêteShell

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

Les clés de lecture sont secrètes. Appelez l’API depuis votre propre serveur, et ne placez jamais une clé de lecture dans le code source d’une page ni dans un navigateur.

L’API de lecture n’est incluse que dans certains forfaits, indiqués dans les Forfaits. Sur les autres, chaque appel répond 402.

Limites de débit

Chaque clé dispose de sa propre réserve de requêtes, qui se remplit en continu. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà de la limite, la réponse est 429, et Retry-After donne le nombre de secondes à attendre.

Périodes, filtres et pages

range est une période prédéfinie qui se termine maintenant. from et to prennent des dates dans le fuseau horaire du projet, ou des date-heures ISO 8601. Une période qui remonte plus loin que les données conservées par le projet est refusée avec range_exceeds_retention.
Chaque dimension est aussi un filtre, par exemple device=mobile. Ajoutez device_op=is_not pour l’inverser.
Les points d’accès de liste renvoient data et next_cursor. Renvoyez next_cursor comme cursor jusqu’à ce qu’il soit nul.

Période

Période
Paramètre	Type	Description
`range`requête	`string`	Une période prédéfinie qui se termine maintenant. Par défaut 7d, raccourcie à la conservation du projet.`24h7d30d90d`
`from`requête	`string`	Une date (AAAA-MM-JJ) dans le fuseau horaire du projet, ou une date-heure ISO 8601 avec un décalage. Nécessite to.
`to`requête	`string`	Incluse quand c’est une date. Doit être après from. Une date au-delà de la conservation du projet est refusée.

Filtres

devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content

Chaque filtre prend une valeur. Un second paramètre portant le même nom suivi de _op, par exemple device_op, indique comment la valeur est comparée. Sans lui, la valeur doit correspondre exactement.

Opérateurs :isis_notcontainsnot_contains

Filtres
Paramètre	Type	Description
`goal`requête	`uuid`	Uniquement les visiteurs qui ont atteint cet objectif.

Pagination

Pagination
Paramètre	Type	Description
`limit`requête	`integer` de 1 à 1000	Lignes par page, de 1 à 1000. Par défaut 100.
`cursor`requête	`string`	Le next_cursor de la page précédente.

Points d’accès

Généré à partir du document OpenAPI de l’API, version 1.0.0 : 11 points d’accès.

Totaux de la période, avec la période précédente pour comparaison

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres

Champs de la réponse
Champ	Type	Description
`pageviews`	`integer`
`sessions`	`integer`
`visitors`	`integer`
`avgDurationSeconds`	`integer`
`bounceRate`	`number` de 0 à 1
`from`	`string`	Début de la période, ISO 8601 en UTC, inclus.
`to`	`string`	Fin de la période, ISO 8601 en UTC, exclue.
`previous`	`object` ou null	La période de même durée juste avant celle-ci. Nulle quand elle n’a eu aucune session.
`previous.pageviews`	`integer`
`previous.sessions`	`integer`
`previous.visitors`	`integer`
`previous.avgDurationSeconds`	`integer`
`previous.bounceRate`	`number` de 0 à 1

Pages vues, visiteurs et sessions par heure ou par jour, intervalles vides compris

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres

Champs de la réponse
Champ	Type	Description
`from`	`string`
`to`	`string`
`timezone`	`string`	Le fuseau horaire IANA du projet. Les intervalles commencent à minuit ou à l’heure pile, dans ce fuseau.
`bucket`	`string`	`hourdayweek`
`data`	`object[]`
`data[].bucket`	`string`	Le début de l’intervalle en ISO 8601, avec le décalage du fuseau horaire du projet, par exemple 2026-09-27T00:00:00+02:00.
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`data[].sessions`	`integer`

Pages par nombre de pages vues

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Visiteurs et pages vues selon une dimension

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.
`by`requête, obligatoire	`string`	`devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content`

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].label`	`string`	La valeur de la dimension. Vide en l’absence de valeur, par exemple pour une visite sans référent.
`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` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Événements personnalisés avec leurs nombres et leur taux de conversion

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].name`	`string`
`data[].count`	`integer`
`data[].visitors`	`integer`
`data[].conversionRate`	`number` de 0 à 1	Visiteurs ayant envoyé l’événement, sur l’ensemble des visiteurs.
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Pages où les visites ont commencé

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].sessions`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Pages où les visites se sont terminées, avec le taux de sortie

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].path`	`string`
`data[].exits`	`integer`
`data[].pageviews`	`integer`
`data[].exitRate`	`number` de 0 à 1	Sorties sur pages vues du chemin.
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Les entonnoirs du projet

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Pagination

Champs de la réponse
Champ	Type	Description
`data`	`object[]`
`data[].id`	`uuid`
`data[].name`	`string`
`data[].steps`	`object[]`
`data[].windowHours`	`integer`
`data[].createdAt`	`string`
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Combien de sessions ont atteint chaque étape

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.
`funnelId`chemin, obligatoire	`uuid`

Accepte aussi : Période, Filtres

Champs de la réponse
Champ	Type	Description
`name`	`string`
`windowHours`	`integer`
`conversionRate`	`number` de 0 à 1
`steps`	`object[]`
`steps[].label`	`string`
`steps[].entered`	`integer`
`steps[].ofStart`	`number` de 0 à 1
`steps[].ofPrevious`	`number` de 0 à 1
`steps[].droppedOff`	`integer`

Conversions pour chaque objectif

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.

Accepte aussi : Période, Filtres, Pagination

Champs de la réponse
Champ	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` de 0 à 1
`next_cursor`	`string` ou null	À passer comme cursor pour la page suivante. Nul sur la dernière page.

Un jeu de données complet en CSV, jamais tronqué

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

Paramètres
Paramètre	Type	Description
`id`chemin, obligatoire	`uuid`	Le projet auquel appartient la clé de lecture.
`dataset`requête	`string`	`pathspagestimeseriescustom-eventsentry-pagesexit-pagesdevicesbrowsersoscountriesregionscitiesreferrerschannelsutm-sourcesutm-mediumsutm-campaigns`

Accepte aussi : Période, Filtres

Répond avec un fichier CSV qui commence par une ligne d’en-tête.

Erreurs

Une erreur répond en JSON avec un code stable et un message. Basez-vous sur le code : le message peut changer.

Réponses d’erreur
Statut	Codes	Description
`400`	`invalid_payloadinvalid_rangerange_exceeds_retentioninvalid_cursor`	La requête n’est pas valide : un paramètre, la période ou le curseur.
`401`	`unauthenticatedunknown_keykey_revoked`	La clé est absente, inconnue ou révoquée.
`402`	`upgrade_required`	Le forfait de l’organisation n’inclut pas l’API de lecture.
`404`	`not_found`	Le projet n’est pas celui de la clé, ou la ressource n’existe pas.
`429`	`rate_limited`	Trop de requêtes. Attendez le nombre de secondes indiqué par Retry-After.

Le document OpenAPI

Le document lisible par machine se trouve à https://stg.webmetric.io/v1/openapi.json. Importez-le dans un client d’API, ou générez un client typé à partir de lui.