Pour les développeurs

Démarrer avec l'API

Une clé en lecture seule, quinze lectures, vos chiffres dans vos propres outils.

L'API vous donne vos mesures depuis vos propres outils : un tableau de bord interne, un rapport hebdomadaire, un entrepôt de données. Elle est en lecture seule. Elle ne modifie rien dans votre espace, et elle ne déclenche aucune collecte.

L'accès dépend de votre offre : la section Développeurs des réglages de votre espace vous dit si votre espace y a droit, et quand ce n'est pas le cas, elle nomme ce qui ferme l'accès et vous donne le moyen de nous écrire. C'est le seul endroit qui connaisse la réponse pour VOTRE espace : cette page-ci est publique, elle ne peut pas la connaître.

Avant de commencer

Un rôle de propriétaire ou d'administrateur sur l'espace : les réglages d'espace ne s'ouvrent qu'à eux. Sinon, demandez la clé à quelqu'un qui les a.
Une offre qui comprend l'API. Cette page ne peut pas vous le dire ; la section Développeurs, elle, l'affiche pour votre espace et nomme ce qui ferme l'accès quand il est fermé.
De quoi lancer un appel HTTP : curl en ligne de commande, ou le client HTTP de votre langage. Aucune bibliothèque de notre part n'est nécessaire, ni disponible.

Obtenir une clé

Ouvrez la section Développeurs
Ouvrez l'application : depuis un ordinateur, le bouton Ouvrir l'app en haut de cette page y mène directement. Choisissez votre espace, puis Réglages dans le rail de gauche. La section Développeurs est la dernière de cette page de réglages, faites défiler jusqu'en bas.
Choisissez ce que la clé pourra lire
Trois portées, comme l'écran les propose : tout l'espace, c'est-à-dire toutes ses analyses ; une marque, donc les analyses de cette marque seulement ; une analyse et rien d'autre. Dans tous les cas, une clé ne lira jamais plus que la personne qui l'a créée.
Donnez-lui une échéance
Deux durées au choix, 90 jours ou 1 an, et 1 an si vous ne dites rien. Passé ce délai, la clé cesse de répondre et vous en créez une autre : c'est voulu, une clé qui vit sans fin finit par traîner dans un dépôt oublié.
Copiez le secret tout de suite
Il s'affiche une seule fois, juste après la création, et commence par geo_live_. Rangez-le dans votre gestionnaire de secrets avant de fermer la fenêtre. L'écran vous donne aussi, à cet instant, les trois extraits prêts à coller que vous retrouvez sur cette page et sur la suivante, votre vraie clé déjà dedans.

Une clé perdue ne se retrouve pas

Nous ne gardons que son empreinte, jamais le secret : personne chez nous ne peut vous le redonner. Si vous le perdez, révoquez la clé et créez-en une autre. Un espace porte au plus dix clés actives ; au-delà, révoquez avant de créer.

Une clé suit la personne qui l'a créée

Si cette personne quitte l'espace ou si son compte est suspendu, la clé cesse de répondre, quel que soit son état par ailleurs. Créez donc vos clés de service depuis un compte qui reste, et prévenez avant de retirer quelqu'un qui en a créé.

Vous ne voyez pas la section ? Deux causes, et deux seulement. Votre rôle : les réglages d'espace sont réservés aux propriétaires et aux administrateurs, et un administrateur restreint à certaines marques n'y entre pas non plus. Votre offre : la section reste visible, mais un bandeau prend la place du bouton et dit ce qui ferme l'accès. Dans les deux cas la réponse est à l'écran.

Le premier appel

Toutes les adresses partent de https://beta.vizibai.com/api/v1, et chaque appel porte votre clé dans l'en-tête Authorization. Commencez par /me : elle décrit la clé elle-même plutôt que vos données, donc elle répond encore quand une analyse est refusée ou quand la portée de la clé ne couvre rien. Si /me refuse à son tour avec un 403, ce n'est pas votre appel qui est en cause mais l'offre de l'espace : voyez la ligne plan_required de Quand ça refuse.

Collez votre clé à la place du substitut

curl -s https://beta.vizibai.com/api/v1/me \
  -H "Authorization: Bearer geo_live_..."

Ce que rend une clé valide, avec le substitut à la place du préfixe réel

{
  "key": {
    "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "name": "reporting",
    "prefix": "geo_live_...",
    "scope": "tenant",
    "brand": null,
    "pinned_analysis": null,
    "created_at": "2026-08-21T09:12:44.000Z",
    "expires_at": "2027-08-21T09:12:44.000Z",
    "last_used_at": "2026-08-21T09:20:01.000Z"
  },
  "workspace": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme",
    "slug": "acme"
  },
  "plan": {
    "key": "equipe"
  },
  "rate_limit": {
    "per_minute": 60,
    "remaining": 59,
    "reset_after_seconds": 0
  },
  "reach": {
    "analyses": 3
  }
}

Ce que chacun de ces champs vous apprend :

name et prefix : le nom que vous avez donné, et la tête visible de la clé (jamais le secret entier). De quoi reconnaître laquelle de vos clés vient de répondre.
workspace et plan.key : l'espace que la clé lit, et la clé technique de votre offre. Technique, pas commerciale : les libellés sont traduits et renommés, les identifiants non.
rate_limit : votre budget d'appels. Le plafond par minute, ce qu'il vous reste, et le nombre de secondes avant le prochain appel disponible, qui vaut zéro tant qu'il vous reste du budget.
reach.analyses : le nombre d'analyses que cette clé atteint, recalculé à chaque appel. Un zéro ici veut dire clé valide et portée vide : elle fonctionne, elle ne voit simplement aucune analyse.

Le deuxième appel enchaîne : GET /analyses liste ce que la clé couvre, vous y prenez un identifiant, et GET /analyses/{analysis}/metrics vous rend ses chiffres. Les quinze lectures, leurs paramètres et leurs valeurs exactes sont dans la référence de l'API.

Lire la réponse

Une lecture chiffrée commence toujours par le contexte de sa mesure : la fenêtre telle que le serveur l'a comprise, la période à laquelle elle se compare, la collecte quand les chiffres portent sur une collecte précise, la date de mesure, et les recettes d'extraction réellement servies. Vous n'avez donc jamais à deviner ce qui a été mesuré, ni à le recalculer de votre côté.

Un vide ne veut jamais dire zéro

Zéro veut dire mesuré à zéro ; null veut dire qu'il n'y avait rien à mesurer. Les confondre transforme une absence de donnée en mauvaise nouvelle. La Part de sources porte en plus la raison de son null, parce qu'il en a deux qui ne se devinent pas : soit aucune réponse de la fenêtre n'a cité de source, soit l'analyse ne déclare aucun domaine à vous.

Un troisième état existe, et il surprend si on ne l'attend pas : la collecte a bien eu lieu mais l'extraction est en retard. Les mesures valent alors null, un drapeau le dit en toutes lettres, et les volumes disent ce qui a été collecté. Enfin, une analyse qui n'a jamais rien collecté répond 200 et non 404 : elle existe, elle n'a rien à montrer.

Ce que ces chiffres veulent dire n'est pas redit ici : Les trois mesures l'explique une fois pour toutes, pour l'application comme pour l'API. Le guide vous branche, il ne redéfinit rien.

Les listes et leurs pages

Une lecture qui rend une liste ne rend jamais tout d'un coup, et c'est le piège le plus coûteux de l'API : prendre la première page pour la totalité donne un tableau de bord qui se trompe sans rien signaler. Trois champs accompagnent donc toujours les items : next_cursor, truncated et total.

Deux lectures se parcourent vraiment : la liste des analyses et la liste des réponses. Tant que next_cursor n'est pas null, repassez-le tel quel dans le paramètre cursor pour obtenir la suite ; quand il vaut null, vous êtes au bout.
Les autres rendent une page et une seule. Leur next_cursor reste null, et c'est truncated qui vous prévient qu'il existe plus de lignes que rendues. Quand la lecture accepte un limit, c'est lui qui décide combien vous en recevez ; celles qui n'en acceptent pas rendent tout, et leur truncated vaut toujours faux.
Un curseur appartient à la portée qui l'a produit. Rejoué sous une autre fenêtre, il est refusé avec cursor_expired plutôt que de vous servir une page calculée sur une autre collecte. Repartez alors de la première page, sans curseur.

Les bornes de limit ne sont pas les mêmes d'une lecture à l'autre, et l'une d'elles se saute par un offset. La référence les donne, lecture par lecture ; le geste, lui, ne change pas.

Les fenêtres de mesure

Sans rien demander, vous obtenez la dernière collecte terminée. C'est l'unité réelle de la mesure : une fenêtre calendaire peut couper une collecte en deux et faire bouger un chiffre sans qu'aucune IA ait changé d'avis. Demandez une fenêtre calendaire quand vous suivez une tendance, et une paire de dates quand vous rejouez une période précise.

Deux lectures font exception et partent sur 30d : la série temporelle, qui n'aurait qu'un point sur une seule collecte, et la liste des réponses, qui est ancrée sur le calendrier. Les appeler sans rien demander ne rend donc pas la dernière collecte mais trente jours, sans le moindre refus pour vous prévenir : nommez la fenêtre à chaque fois que le chiffre doit être comparable à un autre.

Une valeur qu'une lecture n'accepte pas est refusée, jamais remplacée en silence : c'est ce qui vous évite de comparer deux chiffres qui ne portaient pas sur la même période. Les valeurs acceptées, lecture par lecture, sont dans la référence, qui les tient du code qui les applique.

Le budget d'appels

Le budget se compte par clé et par minute. Son plafond vient de votre offre : la section Développeurs l'affiche, et /me le rend. Toute réponse servie porte trois en-têtes de budget : le plafond, ce qu'il vous reste, et le nombre de secondes avant le prochain appel disponible, qui vaut zéro tant qu'il vous reste du budget. Le 429 les porte aussi, avec un Retry-After : au moment où votre budget compte le plus, vous lisez le plafond atteint et le délai exact, sans le deviner. Les refus tranchés avant le compteur, eux, n'en portent aucun : un 401, un 403. Les quatre noms exacts sont dans la référence.

Au 429, attendez le délai que l'en-tête Retry-After annonce plutôt que de réessayer tout de suite : X-RateLimit-Reset répète ce même délai, et X-RateLimit-Limit vous rappelle le plafond que vous venez d'atteindre.
Ne lancez pas plus d'appels en parallèle que votre plafond par minute : le compteur ne fait pas de crédit.
Dix clés font dix budgets, mais un seul espace. Découper un traitement en dix clés pour aller plus vite est un contournement, pas une solution.
Un assistant branché en MCP puise dans le même budget que votre code, dès lors qu'il porte la même clé.

Quand ça refuse

Un refus a toujours la même forme : un code, un message en anglais, et un numéro de requête, les trois rangés sous une clé error. Le code est ce sur quoi vous branchez votre logique ; le message est figé et volontairement avare ; le numéro de requête est ce qu'il faut nous citer.

Le corps d'un refus, ici celui que rend un espace dont l'offre ne comprend pas l'API

{
  "error": {
    "code": "plan_required",
    "message": "Your plan does not include API access.",
    "request_id": "0f2d5a7c-9b31-4e88-a5d2-6c1e4f70b93a"
  }
}

Branchez-vous donc sur error.code, jamais sur le message, qui peut être reformulé. Le même numéro de requête voyage aussi dans l'en-tête X-Request-Id, et toute réponse en porte un, succès compris : le relever systématiquement dans vos journaux vous évitera de rejouer un appel pour le retrouver.

Code renvoyé	Statut HTTP	Ce que ça veut dire, et quoi faire
`unauthorized`	`401`	L'en-tête `Authorization` manque ou n'a pas la bonne forme. Vérifiez que le mot `Bearer` précède la clé, séparé par une espace.
`key_revoked`	`401`	La clé existe mais ne répond plus : révoquée, arrivée à échéance, ou créée par quelqu'un qui n'a plus accès à l'espace. La section Développeurs affiche laquelle des trois.
`plan_required`	`403`	L'API n'est pas comprise dans l'offre de cet espace. Rien à corriger dans votre code : le bandeau de la section Développeurs nomme ce qui ferme l'accès et ouvre la suite.
`analysis_not_found`	`404`	L'analyse nommée n'existe pas, ou votre clé ne l'atteint pas. Les deux répondent pareil, exprès. Listez les analyses pour voir ce que la clé couvre vraiment.
`not_found`	`404`	La ressource visée à l'intérieur de l'analyse est introuvable : un groupe, une collecte ou une réponse qui n'existe pas, ou qui appartient à une autre analyse.
`invalid_request`	`422`	Un paramètre est refusé : une fenêtre que cette lecture n'accepte pas, une borne de page hors limites, `from` sans `to`, ou une clé que cette lecture ne connaît pas (`?windw=7d`) ou répétée. Dans ces deux derniers cas, le champ `param` de l'erreur nomme la clé en cause. Rien n'est jamais raboté ni ignoré en silence, donc corrigez la requête plutôt que de réessayer.
`cursor_expired`	`422`	Le curseur de pagination a été rejoué sous une autre portée que celle qui l'a produit. Repartez de la première page, sans curseur.
`rate_limited`	`429`	Le budget de la clé est épuisé pour la minute en cours. Ce refus porte les trois en-têtes de budget et un `Retry-After` : attendez ce délai avant de reprendre. Réessayer aussitôt ne fait que creuser le retard. Les en-têtes sont nommés dans la référence.
`internal_error`	`500`	Une panne de notre côté. Réessayez une fois, puis écrivez à tech@vizibai.com avec le numéro de requête de la réponse : c'est lui qui nous mène à la trace.
`rate_limit_unavailable`	`503`	Une lecture dont dépend la garde de l'appel a échoué : le compteur de budget, ou la vérification de ce que votre clé a le droit d'atteindre. L'API refuse plutôt que de servir sans garde. C'est passager, réessayez dans quelques secondes ; si cela dure, écrivez à tech@vizibai.com.
`upstream_timeout`	`503`	L'entrepôt de mesures n'a pas répondu à temps. Il s'endort après une période creuse et met une vingtaine de secondes à se réveiller : réessayez une fois avant de conclure à une panne.
`api_disabled`	`503`	L'API entière est coupée, pour tout le monde, le temps d'une opération de notre côté. Rien à changer chez vous : la réponse annonce le délai à respecter dans son en-tête `Retry-After`, reprenez après. Si la coupure se prolonge, écrivez à tech@vizibai.com.

Un 404 ne dit pas laquelle des deux causes, et c'est voulu

Une analyse qui n'existe pas et une analyse que votre clé n'a pas le droit de lire répondent exactement la même chose. Sans cette règle, une clé pourrait sonder l'existence de ce qu'elle n'a pas le droit de voir, une réponse à la fois. Pour savoir ce que votre clé atteint, listez les analyses : c'est la seule source honnête.

Les quatre façons dont une clé meurt

Elle a été révoquée, elle est arrivée à échéance, la personne qui l'a créée n'a plus accès à cet espace, ou l'API n'est plus comprise dans l'offre. Les trois premières répondent key_revoked en 401 et exigent une nouvelle clé ; la quatrième répond plan_required en 403, et celle-là ne se corrige pas dans votre code. Prévoyez donc deux branches, pas une. La section Développeurs, elle, affiche laquelle des quatre, clé par clé.

Ce que l'API ne fait pas

Savoir ce qui n'existe pas vous coûte moins cher que de le découvrir en le codant. La liste est tenue à jour ici, et nulle part ailleurs.

Aucune écriture, déclenchement d'une collecte compris. L'API lit ce que le produit a mesuré, elle ne lui demande rien.
Pas d'OAuth : une clé est le seul moyen de s'authentifier, donc pas de connecteur en un clic dans les outils qui l'attendent.
Pas de webhooks : rien ne vous est poussé, c'est vous qui appelez.
Aucun cache entre deux appels : chaque lecture repart de la donnée. Si vous appelez deux fois de suite, vous payez deux appels pour la même réponse.
Pas de trafic IA, d'audit de crawlabilité, de flux, de médias, de communautés, de netlinking, de vue par marque, de duel de pages, d'atelier de contenu, de briefs ni de guides. Ces lectures existent dans l'application, elles ne sont pas sous contrat ici.
Pas de chiffres au grain de la question sur le catalogue de questions : ils vivent sur les questions d'un groupe, et seulement là.
Pas de décalage de surlignage. La lecture d'une réponse rend son texte et les marques qui y apparaissent, chacune avec son rang d'apparition (position), jamais sa position en caractères : celle-là se recalcule chez vous, en cherchant le nom dans le texte.
Pas d'étage revendeur : une clé lit un espace, jamais un portefeuille d'espaces.

Les limites du produit sont ailleurs, et ne parlent pas de la même chose : Ce que VizibAI ne fait pas. Cette page-ci ne parle que du contrat de l'API.

Et ensuite

La référence de l'API donne les quinze lectures une par une, leurs paramètres et leurs fenêtres, ainsi que le document machine dont tout générateur sait tirer un client. Et si vous préférez poser vos questions en français plutôt qu'en requêtes, Brancher un assistant (MCP) montre comment votre assistant lit ces mêmes chiffres tout seul.