> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/insights-api.md).

# API Insights

Interroger les événements Wallet, les journaux, les requêtes et les pages vues à l’échelle du tenant avec l’API Insights et Kusto Query Language (KQL) pour le reporting et l’analyse.

Le **API Insights** donne accès à la base de données d'utilisation de The Wallet Crew. Interrogez les journaux, les événements, les requêtes et les vues de page à l'aide de [Kusto Query Language (KQL)](https://learn.microsoft.com/en-us/kusto/query/).

Cette API est conçue pour les équipes techniques qui extraient des données de manière programmatique. Utilisez-la pour des plages de dates personnalisées, des regroupements personnalisés, l'ingestion BI et des rapports automatisés, lorsque le tableau de bord ne suffit pas.

{% hint style="info" %}
Le **Analytique** les tableaux de bord de la console d'administration sont construits sur les mêmes données d'événements. Tout ce qu'ils affichent peut aussi être interrogé ici, avec plus de flexibilité sur les regroupements, les filtres et les plages de dates. Pour une vue sans code, utilisez [Tableaux de bord Analytics](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/analytics-dashboards.md). Pour les exportations CSV au niveau des enregistrements, voir [Exporter les données](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/report.md).
{% endhint %}

## Cas d'utilisation courants

* Alimentez Tableau, Looker ou Power BI avec les comptages d'installation et de désinstallation.
* Automatisez un rapport hebdomadaire des performances du programme par magasin ou par région.
* Créez un entonnoir d'activation personnalisé en corrélant `Carte:Created` avec `Carte:Installed`.
* Interrogez les événements de scan pour créer une vue analytique des utilisations.
* Validez la diffusion de la campagne en comparant `Carte:NotificationSent` avec les pics d'installation.

## Authentification et autorisations

* Envoyez la clé API du locataire dans l'en-tête `X-API-KEY` .
* Créez la clé dans **Paramètres → Contrôle d'accès → Clés API et secrets** (voir [Clés API et secrets](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/platform/api-keys-and-secrets.md)). Elle nécessite le scope **`tenant.insights:read`**. Une clé manquante ou invalide renvoie `401`. Une clé sans le scope renvoie `403`.
* Scope mono-tenant : une clé interroge uniquement son propre tenant. La plateforme ajoute le filtre tenant.

## Rétention et limites de débit

* **Journaux** : conservés **45 jours**
* **Événements** et **pages vues** : conservés **indéfiniment**

**Limite de débit** : 60 appels par minute par défaut. Pour demander une limite plus élevée, ouvrez un ticket d'assistance.

L'API ne met pas les résultats en cache. Mettez-les en cache de votre côté lorsque vous interrogez.

## Point de terminaison

Toutes les requêtes utilisent cette opération :

## Run an analytics query

> Reference parameters by name, e.g. \`{"query": "Events | where Name == eventName | take 100", "parameters": {"eventName": "Pass:Installed"}}\`.

```json
{"openapi":"3.1.1","info":{"title":"The Wallet Crew internal API","version":"v1"},"tags":[{"name":"Insights"}],"servers":[{"url":"https://api.thewalletcrew.io","description":"Production Server"},{"url":"https://api-qa.thewalletcrew.io","description":"Staging Server"}],"security":[{"admin-bearer":["tenant.insights:read"]},{"apiKey":[]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"QueryRequest":{"required":["query"],"type":"object","properties":{"query":{"type":"string","description":"KQL text. Only analytics-schema tables and columns are accepted, over the tenant's own data; invalid KQL returns 400 with a diagnostic."},"parameters":{"type":"object","additionalProperties":{"type":"string"},"description":"Query parameter values by name, passed as KQL strings. Names start with a letter or `_`, then letters, digits or `_`. `params_tenantId` is reserved."},"options":{"description":"Execution settings; defaults apply when omitted.","$ref":"#/components/schemas/QueryOptions"}},"additionalProperties":false,"description":"KQL query to run."},"QueryOptions":{"type":"object","properties":{"maxRows":{"type":"integer","description":"Row limit, 1 to 100,000 (default). Out of range, or more matching rows, returns 400: aggregate or narrow the query.","format":"int32"}},"additionalProperties":false,"description":"Execution settings."},"QueryResponse":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"string"},"description":"Column names, in projection order."},"rows":{"type":"array","items":{"type":"array","items":{}},"description":"One array per row, one value per column. Empty cells are `null`, `dynamic` cells are JSON values, dates are UTC."}},"additionalProperties":false,"description":"Query result."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/insights/query":{"post":{"tags":["Insights"],"summary":"Run an analytics query","description":"Reference parameters by name, e.g. `{\"query\": \"Events | where Name == eventName | take 100\", \"parameters\": {\"eventName\": \"Pass:Installed\"}}`.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Query text, parameters and options.","content":{"application/json":{"schema":{"description":"KQL query to run.","$ref":"#/components/schemas/QueryRequest"}},"text/json":{"schema":{"description":"KQL query to run.","$ref":"#/components/schemas/QueryRequest"}},"application/*+json":{"schema":{"description":"KQL query to run.","$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Column names and rows.","content":{"text/plain":{"schema":{"description":"Query result.","$ref":"#/components/schemas/QueryResponse"}},"application/json":{"schema":{"description":"Query result.","$ref":"#/components/schemas/QueryResponse"}},"text/json":{"schema":{"description":"Query result.","$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"Empty or invalid query, unknown table or column, invalid or reserved parameter name, `maxRows` out of range, or more rows than `maxRows`.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"The caller is not authenticated.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"The caller lacks the `tenant.insights:read` scope, or the endpoint is not enabled for the tenant.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"The tenant does not exist.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"429":{"description":"Over 60 requests per minute to this endpoint for the tenant (default limit); retry after `Retry-After`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent when the limiter knows it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"504":{"description":"Query ran too long; aggregate or narrow it."}}}}}}
```

```http
POST /api/{tenantId}/insights/query
X-API-KEY: <API_KEY>
Content-Type: application/json
```

Les URL de base des environnements de production et de QA se trouvent dans [Bien démarrer avec l'API](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/getting-started-with-the-api.md).

* `{tenantId}` = votre identifiant de locataire
* Le corps de la requête doit contenir une `requête` chaîne en **KQL**.
* Carte les valeurs via `paramètres` (paramètres de requête nommés) au lieu de les concaténer dans la requête. Les noms commencent par une lettre ou `_`; `params_tenantId` est réservé.
* `options.maxRows` définit la limite de lignes, de 1 à 100 000 (la valeur par défaut). Une requête qui correspond à davantage de lignes, ou une valeur hors plage, renvoie `400`: agréguez ou restreignez la requête.
* `400` couvre également une requête vide ou invalide ainsi qu’une table ou une colonne inconnue. `504` signifie que la requête a duré trop longtemps.

Une première requête, qui renvoie les 50 dernières erreurs. L’hôte `api.thewalletcrew.io` est l’URL de base de production :

```bash
curl -X POST "https://api.thewalletcrew.io/api/<TENANT_ID>/insights/query" \
  -H "X-API-KEY: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Logs | where Timestamp > ago(1h) and SeverityLevel >= 3 | project Timestamp, CategoryName, OperationId, Message | order by Timestamp desc | take 50"
  }'
```

La réponse est sous forme tabulaire :

```json
{
  "columns": ["Timestamp", "CategoryName", "OperationId", "Message"],
  "rows": [
    ["2026-09-14T19:15:02.117Z", "Runtime.Http...", "4454c9229...", "..."]
  ]
}
```

## Tables et schéma

La base de données Insights expose ces tables. Les noms des tables et des colonnes sont sensibles à la casse. Il n’y a pas de `Métriques` table.

| Table        | Ce qu’elle contient                                                   | Colonnes principales                                                                              |
| ------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `Événements` | Des événements métier tels que `Carte:Created` ou `Customer:Upserted` | `Timestamp`, `Name`, `OperationId`, `UserId`, `EventData` (dynamic)                               |
| `Journaux`   | Erreurs et traces de l’activité de la plateforme, pour le débogage    | `Timestamp`, `SeverityLevel`, `Message`, `CategoryName`, `OperationId`, `Propriétés` (dynamic)    |
| `Requêtes`   | Requêtes API                                                          | `Timestamp`, `Name`, `Durée`, `Code de résultat`, `Succès`, `OperationId`                         |
| `Pages vues` | Pages vues des pages d’inscription et de téléchargement               | `Timestamp`, `Name`, `URL`, `Nom de la mise en page`, `Type de mise en page`, `Agent utilisateur` |

Chaque table a un `ID du locataire` colonne. Les détails de l'événement se trouvent dans `EventData`par exemple `EventData.passId`.

## Requêtes courantes

### Compter les upserts client

```kql
Événements
| where Timestamp > ago(30d)
| where Name == "Customer:Upserted"
| summarize CustomerUpserts = count()
```

### Compter les installations de Carte

```kql
Événements
| where Timestamp > ago(30d)
| where Name == "Carte:Installed"
| summarize CarteInstallations = count()
```

### Compter les requêtes API par jour

```kql
Requêtes
| where Timestamp > ago(30d)
| summarize RequestsPerDay = count() by bin(Timestamp, 1d)
```

### Compter les redirections par jour

```kql
Événements
| where Timestamp > ago(30d)
| where Name == "Redirect:Redirected"
| summarize RedirectsPerDay = count() by bin(Timestamp, 1d)
```

### Compter les pages vues par mise en page

```kql
Pages vues
| where Timestamp > ago(30d)
| summarize PageViews = count() by LayoutName
```

### Filtrer sur une propriété structurée

```kql
Journaux
| where Timestamp > ago(2d)
| where tostring(Properties.requestPath) startswith "/api/"
| summarize Calls = count() by tostring(Properties.requestPath)
| order by Calls desc
| take 25
```

### Taux d'erreur en pourcentage

```kql
Journaux
| where Timestamp > ago(24h)
| summarize Total = count(), Failures = countif(SeverityLevel >= 3)
| extend ErrorRate = round(100.0 * Failures / Total, 2)
```

### Tout ce qui touche une Carte, dans les journaux

```kql
Journaux
| where Timestamp > ago(30d)
| où * contient « <CARTE_SERIAL> »
| projet Horodatage, Niveau de gravité, Nom de catégorie, Message
| trier par Timestamp décroissant
```

Pour les recettes d’erreur et de trace sur `Journaux`, voir [Récupérer les journaux de la plateforme](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/retrieve-platform-logs.md).

### Historique d’une Carte, avec un paramètre

```json
{
  "query": "declare query_parameters(passId:string); Events | where Timestamp > ago(90d) | where tostring(EventData.passId) == passId | project Timestamp, Name, EventData | order by Timestamp desc | take 50",
  "parameters": { "passId": "{passId}" },
  "options": { "maxRows": 1000 }
}
```

### Types de paramètres et pagination

Les paramètres arrivent sous forme de chaînes : convertissez-les dans la requête avec `todatetime()` ou `toint()`. Parcourez de grands résultats en numérotant et en découpant les lignes :

```json
{
  "query": "Logs\n| where Timestamp between (todatetime(start) .. todatetime(stop))\n| where * contains searchQuery\n| order by Timestamp desc\n| serialize rowNum = row_number()\n| where rowNum > (toint(pageIndex) * toint(pageSize))\n  and rowNum <= ((toint(pageIndex) + 1) * toint(pageSize))\n| project Timestamp, Message, OperationName, OperationId, SeverityLevel, CategoryName, Properties",
  "parameters": {
    "start": "2026-09-01T00:00:00.000Z",
    "stop": "2026-09-14T23:59:59.999Z",
    "searchQuery": "outdated",
    "pageIndex": "0",
    "pageSize": "100"
  }
}
```

Une requête qui renvoie plus de lignes que `options.maxRows` échoue volontairement au lieu de renvoyer un résultat tronqué qui semble complet.

## Noms d’événements courants

Le `Name` colonne de `Événements` contient le nom de l’événement. Les webhooks utilisent les mêmes noms. Chaque événement est défini dans [Ce que Wallet Crew suit](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/what-the-wallet-crew-tracks.md#event-reference). Chaque événement répond à une question métier différente :

| Événement                | Ce qu’il capture                                                                                                          | Exemple de question                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Carte:Created`          | Un enregistrement de Carte a été créé.                                                                                    | Combien de Cartes ont été émises ce mois-ci par magasin ?                        |
| `Carte:Installed`        | Une Carte a été ajoutée à Apple Wallet ou Google Wallet, avec sa source dans `registrationSource` (média, tags, origine). | Quelle campagne e-mail a généré le plus d’installations la semaine dernière ?    |
| `Carte:Uninstalled`      | Une Carte a été supprimée de son dernier appareil dans un Wallet.                                                         | Quel est le taux de désinstallation par programme ?                              |
| `Carte:Updated`          | Les données de la Carte ont changé.                                                                                       | Combien de Cartes ont été mises à jour après la dernière campagne ?              |
| `Carte:UpdateSent`       | Une mise à jour push a été envoyée à un appareil.                                                                         | Les mises à jour atteignent-elles les appareils de manière fiable ?              |
| `Carte:Scanned`          | Le code-barres d’une Carte a été scanné.                                                                                  | Combien de scans par jour ont eu lieu dans chaque emplacement ?                  |
| `Carte:NotificationSent` | Une notification push a été envoyée.                                                                                      | Combien de notifications ont été envoyées par programme ce mois-ci ?             |
| `Carte:LinkOpened`       | Le titulaire a appuyé sur un lien suivi de la Carte.                                                                      | Quels liens de la Carte les titulaires ouvrent-ils ?                             |
| `Customer:Upserted`      | Un client a été créé ou mis à jour.                                                                                       | Combien de profils client ont été créés ou mis à jour cette semaine ?            |
| `Redirection : redirigé` | Un utilisateur a ouvert une URL raccourcie (redirection).                                                                 | Combien de scans du code QR en magasin ont atteint le formulaire d'inscription ? |

## Filtres

Filtrer un `Événements` requête sur la date (`Timestamp`), l'événement (`Name`), et les champs de `EventData`:

* Le `Carte:Installed`, la source d'installation est dans `EventData.registrationSource`: `moyen`, `balises` (un tableau, lisez-le avec `mv-expand`), `origine` (l’URL de la page ; déduisez l’hôte avec `parse_url`) et `agent utilisateur`.
* Chaque `Carte:*` l’événement contient `EventData.passType` (le modèle de carte), `EventData.metadata.<key>` (les métadonnées de la carte, telles que `storeId`) et `EventData.passTypeTags`.

Pour découvrir la structure de `EventData`, retourner un événement brut :

```kql
Événements
| where Timestamp > ago(7d)
| where Name == "Carte:Created"
| project Timestamp, Name, EventData
| trier par Timestamp décroissant
| take 1
```

## Requête d'un assistant IA (MCP)

Un assistant connecté via MCP peut exécuter les mêmes requêtes. La connexion MCP ne nécessite aucune clé API : connectez-vous avec les identifiants de la console d'administration (OAuth). Voir [Protocole de contexte du modèle (MCP)](https://docs.thewalletcrew.io/connectors/fr/model-context-protocol-mcp.md) pour les points de terminaison et la configuration.

| Outil                     | Utiliser                                                                                     |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `twc_insights_schema_get` | Confirmez les tables, colonnes et noms d’événements disponibles, avec des exemples concrets. |
| `twc_requête_analyses`    | Exécutez KQL et renvoyez les résultats.                                                      |

Modèles de prompts pour les enquêtes :

> Afficher toutes les erreurs et tous les avertissements des dernières 24 heures, groupés par composant. Pour les trois plus bruyants, expliquer le composant et les messages.

> Rechercher les lignes de journal pour Carte `<PASS_ID>` des 7 derniers jours. Reconstituez ce qui s’est passé et identifiez les étapes ayant échoué.

> Opération `<OPERATION_ID>` a échoué. Récupérez ses lignes dans l'ordre et identifiez à quel endroit cela a échoué.

> Comparez le volume d'erreurs de cette semaine à celui de la semaine dernière. Signalez les composants dont les échecs ont plus que doublé.

{% hint style="info" %}
Gardez une plage de temps étroite. Chaque appel d'outil est limité à deux minutes, et les requêtes trop larges `Journaux` peuvent atteindre cette limite.
{% endhint %}

## Dépannage

* **401 Non autorisé**
  * Assurez-vous que la clé API est valide.
* **403 Interdit**
  * La clé ne dispose pas `tenant.insights:read`, ou les analyses ne sont pas activées pour le locataire.
* **429 Trop de requêtes**
  * La limite de débit a été dépassée. Mettez en place des tentatives avec temporisation exponentielle, et regroupez avec `résumer` au lieu de boucles d'interrogation.
* **La requête prend trop de temps**
  * `504` signifie que la requête a été exécutée trop longtemps. Simplifiez la requête ou réduisez la fenêtre temporelle.
  * Évitez les requêtes non bornées sur de grandes tables.
* **Aucune ligne alors que des lignes étaient attendues**
  * Vérifiez d'abord la fenêtre de rétention de la table, puis la casse des noms de table et de colonne.
* **`400` sur une requête apparemment correcte**
  * Un nom de colonne est incorrect, ou un paramètre n'a pas de conversion.
* **Nombres inhabituels**
  * Confirmez l'environnement. QA contient des données de test, pas des données de production.

## FAQ

<details>

<summary><strong>Puis-je interroger plusieurs locataires ?</strong></summary>

Non. Une clé interroge uniquement son propre locataire : la plateforme ajoute le filtre de locataire à chaque requête.

</details>

<details>

<summary><strong>Puis-je exporter les résultats en CSV/JSON ?</strong></summary>

Pas directement via l'API. La réponse est un JSON avec `colonnes` et `lignes`: convertissez-le localement. Les tableaux de bord de la console d'administration peuvent exporter en CSV.

</details>

<details>

<summary><strong>Les résultats de requête peuvent-ils contenir des données personnelles ?</strong></summary>

Les champs disponibles dépendent de la configuration du locataire et des intégrations. Traitez les résultats de requête comme des données opérationnelles et appliquez les politiques d'accès et de conservation de l'organisation.

</details>

<details>

<summary><strong>Puis-je configurer des alertes (seuils, déclencheurs) ?</strong></summary>

Pas pour le moment.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/insights-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
