> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtenir les analytics des crawlers

> Récupérez l’activité conservée des crawlers IA, la couverture de livraison et les observations par page d’une marque.

Récupère l’activité des crawlers IA observée via l’intégration de journaux configurée pour la marque. L’endpoint renvoie des agrégats quotidiens et des observations par page. Il ne renvoie jamais d’événements de journaux bruts ni de trafic humain.

Tous les totaux d’occurrences, ventilations par crawler et classements de pages utilisent l’ensemble public des identités User-Agent propres à l’IA, observables et prises en charge. Le registre d’ingestion peut reconnaître d’autres identités pour la classification et la compatibilité, mais l’endpoint les exclut de ses analytics publics. La classification se fonde sur le jeton User-Agent reçu ; elle ne vérifie ni l’IP source ni le DNS inverse.

<Note>
  Cet endpoint exige une offre Business, Enterprise ou Agency Business active, ou une activation explicite de la fonctionnalité Analytics des crawlers pour l’équipe. Les résultats sont des observations : vérifiez `coverage` avant d’interpréter des volumes ou de comparer des périodes.
</Note>

<ParamField header="Authorization" type="string" required>
  Jeton bearer. Exemple : `Bearer qw-api-xxx`
</ParamField>

## Paramètres de chemin

<ParamField path="brandId" type="string" required>
  Identifiant unique de la marque.
</ParamField>

## Paramètres de requête

<ParamField query="range" type="string" default="30d">
  Préréglage de jours d’analyse inclus, dans le fuseau horaire IANA de l’intégration : `24h` est le jour d’analyse en cours, `7d` ce jour et les six précédents, `30d` ce jour et les 29 précédents. `24h` n’est pas une fenêtre glissante de 24 heures.
</ParamField>

<ParamField query="state" type="string" default="all">
  Filtre d’état des pages : `all`, `new`, `hot` ou `neglected`.
</ParamField>

<ParamField query="page" type="number" default="1">
  Numéro de page, à partir de 1. Maximum : `10000`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Taille de page. Maximum : `100`.
</ParamField>

## Signification des états de page

* `new` : la première observation conservée de la page date des 7 derniers jours, borne incluse (`firstSeenAt >= now - 7 days`).
* `hot` : la page fait partie du premier décile en occurrences de crawlers pris en charge sur les 7 jours d’analyse en cours, a de l’activité sur au moins 2 de ces jours et n’est pas délaissée.
* `neglected` : la dernière observation conservée de la page est strictement antérieure à la limite de 30 jours.

`new` et `hot` peuvent coexister. `neglected` est exclusif. La fenêtre de `hot` ne dépend pas du `range` demandé.

## Réponse

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi.
</ResponseField>

<ResponseField name="brand" type="object">
  `id`, `name` et `domain` de la marque.
</ResponseField>

<ResponseField name="connected" type="boolean">
  Indique si l’intégration est active, non désactivée, et dispose d’au moins une clé active non révoquée.
</ResponseField>

<ResponseField name="lifecycle" type="string | null">
  Cycle de vie actuel de l’intégration, ou `null` s’il n’y a pas d’intégration.
</ResponseField>

<ResponseField name="health" type="string | null">
  Santé actuelle de l’intégration, ou `null` s’il n’y a pas d’intégration.
</ResponseField>

<ResponseField name="range" type="object">
  Dates demandées et effectives, nombres de tranches observées et vérifiées, état de troncature et horodatage `asOf`.
</ResponseField>

<ResponseField name="coverage" type="object">
  <Expandable title="Détail de la couverture">
    <ResponseField name="hasObservations" type="boolean">Indique si la plage sélectionnée contient au moins une occurrence publique prise en charge.</ResponseField>
    <ResponseField name="dataStatus" type="string">`observed` lorsque des observations prises en charge existent sans lacune connue ; `not_measured` lorsqu’il n’y en a aucune et qu’aucune lacune n’est connue ; `incomplete_ingestion` en cas de limite de quota ou de lacune du fournisseur, avec ou sans observations.</ResponseField>
    <ResponseField name="ingestCoverageFlags" type="number">Indicateurs binaires : `1` livraison non vérifiée, `2` quota limité et `4` lacune du fournisseur.</ResponseField>
    <ResponseField name="countPrecision" type="string">`exact` ; `at_least_once` lorsque des renvois reconditionnés peuvent dupliquer des observations ; ou `capped` lorsqu’un volume dépasse la précision numérique sûre.</ResponseField>
    <ResponseField name="deliveryContinuity" type="string">`verified` lorsque chaque tranche écoulée est vérifiée ; `incomplete` en cas de lacune connue ou de changement de profil ; sinon `unverified`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalOccurrences" type="number | null">
  Occurrences observées de l’ensemble public des crawlers pris en charge sur la plage effective. Une valeur numérique n’est renvoyée que si au moins une synthèse publique prise en charge a un nombre de requêtes positif ; sinon la valeur est `null`, et non un zéro mesuré. En cas d’ingestion incomplète, une valeur numérique peut rester partielle.
</ResponseField>

<ResponseField name="identifiedPageOccurrences" type="number">
  Occurrences associées à une identité de page conservée.
</ResponseField>

<ResponseField name="redirectOccurrences" type="number">
  Requêtes ayant renvoyé une redirection.
</ResponseField>

<ResponseField name="notFoundOccurrences" type="number">
  Requêtes ayant renvoyé `404`.
</ResponseField>

<ResponseField name="otherErrorOccurrences" type="number">
  Autres réponses d’erreur observées.
</ResponseField>

<ResponseField name="buckets" type="array">
  Totaux quotidiens, ventilations par crawler, totaux d’erreurs et métadonnées de couverture.
</ResponseField>

<ResponseField name="crawlerStats" type="array">
  Totaux par crawler de l’ensemble public pris en charge, avec son nom affiché, son type de robot et sa ventilation des erreurs.
</ResponseField>

<ResponseField name="pages" type="array">
  <Expandable title="Observation de page">
    <ResponseField name="pathId" type="string">Identité stable de la page.</ResponseField>
    <ResponseField name="path" type="string">Chemin observé ou pseudonyme interne.</ResponseField>
    <ResponseField name="isPseudonymized" type="boolean">Si `true`, ne reconstituez pas d’URL à partir de `path` et n’y faites pas de lien.</ResponseField>
    <ResponseField name="firstSeenAt" type="string">Horodatage de la première observation.</ResponseField>
    <ResponseField name="lastSeenAt" type="string">Horodatage de l’observation la plus récente.</ResponseField>
    <ResponseField name="lifetimeCount" type="number">Nombre d’occurrences conservé sur toute la durée.</ResponseField>
    <ResponseField name="states" type="array">États calculés. `new` et `hot` peuvent coexister ; `neglected` est exclusif.</ResponseField>
    <ResponseField name="occurrences" type="number">Occurrences sur la plage sélectionnée.</ResponseField>
    <ResponseField name="crawlerOccurrences" type="object">Nombre d’occurrences par nom de crawler.</ResponseField>
    <ResponseField name="uniqueCrawlers" type="number">Crawlers distincts observés.</ResponseField>
    <ResponseField name="statusGroups" type="object">Totaux par groupe de statuts HTTP.</ResponseField>
    <ResponseField name="crawlerTypes" type="object">Totaux des crawlers de recherche en direct, d’entraînement et autres.</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Les synthèses quotidiennes par page et par crawler conservent 30 jours d’analyse. Les identités de pages durables conservent la première et la dernière observation ainsi que le total sur toute la durée au-delà de cette fenêtre. Les paramètres de requête et les fragments sont supprimés ; les chemins d’apparence sensible ou trop longs peuvent être remplacés par un pseudonyme irréversible propre à l’intégration.
</Note>

<ResponseField name="pagination" type="object">
  `page` (à partir de 1), `limit`, `totalItems`, `totalPages` et `hasMore`.
</ResponseField>

<ResponseField name="rawEventsAvailable" type="boolean">
  Toujours `false`. Cet endpoint n’expose pas les événements de journaux bruts.
</ResponseField>

<ResponseField name="humanTrafficIncluded" type="boolean">
  Toujours `false`.
</ResponseField>

## Exemple de requête

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/crawler-analytics?range=7d&state=hot&limit=25" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Interpréter les données manquantes ou incomplètes

* Considérez `totalOccurrences: null` comme non mesuré. Ne le convertissez pas en zéro.
* Vérifiez `coverage.dataStatus`, `countPrecision` et `deliveryContinuity` avant de comparer des périodes.
* Utilisez `range.startDate` et `range.endDate` comme fenêtre de comparaison effective.
* Ne construisez pas d’URL publique à partir d’une page dont `isPseudonymized` vaut `true`.

## Erreurs

| Statut | Signification |
| - | - |
| `400` | Valeur de plage, d’état ou de pagination invalide |
| `401` | Jeton d’API manquant ou invalide |
| `403` | L’équipe n’a ni offre active éligible ni activation explicite d’Analytics des crawlers |
| `404` | Marque introuvable ou inaccessible à l’équipe du jeton |
| `429` | Limite de débit dépassée ; respectez `Retry-After` |

Consultez [Analytics des crawlers](/fr/documentation/measure/crawler-analytics) pour la configuration et l’interface produit, et [Limites de débit](/fr/developers/rate-limits) pour la gestion des nouvelles tentatives.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.