# Analyser et consulter l'utilisation des compteurs

Découvrez comment interroger et analyser les données d'utilisation des compteurs.

Utilisez l’API Meter Usage Analytics pour interroger et analyser les données d’utilisation des compteurs de vos clients. Cela vous permet de créer des dashboards d’utilisation personnalisés, de générer des rapports et de déterminer les habitudes de consommation de vos compteurs.

Cette API est disponible en aperçu public.  pour demander l’accès à cette API.

## Interroger les données d’utilisation

L’API Meter Usage Analytics renvoie des données d’utilisation agrégées pour un client au cours d’un intervalle de temps spécifié. Vous pouvez rechercher des données par période, filtrer par dimensions de compteur et effectuer des requêtes sur plusieurs compteurs simultanément.

> Les paramètres de l’API ont été mis à jour dans la version bêta du 2025-09-30. Consultez le[journal des modifications](https://docs.stripe.com/changelog/clover/2025-09-30/update-meter-usage-fields.md) pour comprendre comment les formats de requête et de réponse ont évolués.

### Récupérer l’utilisation pour un seul dispositif de mesure

Récupérez les données d’utilisation d’un client et d’un dispositif de mesure spécifiques sur une période donnée :

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starts_at=1735689600 \
  -d ends_at=1738368000 \
  -d customer={{CUSTOMER_ID}} \
  -d "meters[0][meter]"={{METER_ID}} \
  -d value_grouping_window=day \
  --data-urlencode timezone="America/New_York"
```

### Récupérez l’utilisation d’un dispositif de mesure filtré et regroupé par dimension

Interrogez les données d’utilisation filtrées par niveau premium et regroupées par modèle&nbsp;:

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starts_at=1735689600 \
  -d ends_at=1738368000 \
  -d customer={{CUSTOMER_ID}} \
  -d "meters[0][meter]"={{METER_ID}} \
  -d "meters[0][dimension_group_by_keys][0]"=model \
  -d "meters[0][dimension_filters][tier]"=premium \
  -d value_grouping_window=day
```

### Récupération de l’utilisation d’un compteur filtrée par locataire

Interrogez les données d’utilisation filtrées par niveau premium et regroupées par modèle&nbsp;:

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starts_at=1735689600 \
  -d ends_at=1738368000 \
  -d customer={{CUSTOMER_ID}} \
  -d "meters[0][meter]"={{METER_ID}} \
  -d "meters[0][tenant_filters][user_id]"=a8238bf39a1 \
  -d value_grouping_window=day
```

### Récupérez l’utilisation sur plusieurs mètres

Interrogez l’utilisation sur plusieurs compteurs avec différents filtres et groupes&nbsp;:

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starts_at=1735689600 \
  -d ends_at=1738368000 \
  -d customer={{CUSTOMER_ID}} \
  -d "meters[0][meter]"={{METER_ID_1}} \
  -d "meters[0][dimension_group_by_keys][0]"=model \
  -d "meters[0][dimension_group_by_keys][1]"=tier \
  -d "meters[1][meter]"={{METER_ID_2}} \
  -d "meters[1][dimension_filters][region]"=us-east \
  -d value_grouping_window=day
```

### Créez des dashboards d’utilisation

Vous pouvez utiliser les données de l’API pour créer des visualisations, telles que des graphiques empilés qui montrent l’utilisation dans différentes dimensions. L’exemple suivant montre comment structurer les données d’un graphique qui montre l’utilisation de l’API par modèle&nbsp;:

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starts_at=1735689600 \
  -d ends_at=1738368000 \
  -d customer={{CUSTOMER_ID}} \
  -d "meters[0][meter]"={{METER_ID}} \
  -d "meters[0][dimension_group_by_keys][0]"=model \
  -d value_grouping_window=day
```

Voici un exemple de réponse à cette requête&nbsp;:

**Afficher la réponse**

```json
{
  "data": [
    {
      "starts_at": 1735689600,
      "ends_at": 1735776000,
      "value": 1500,
      "meter": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "starts_at": 1735689600,
      "ends_at": 1735776000,
      "value": 800,
      "meter": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    },
    {
      "starts_at": 1735776000,
      "ends_at": 1735862400,
      "value": 2100,
      "meter": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "starts_at": 1735776000,
      "ends_at": 1735862400,
      "value": 950,
      "meter": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    }
  ]
}
```

Utilisez cet exemple de code pour extraire des données de l’API dans votre back-end et les afficher aux utilisateurs sous la forme d’un diagramme à barres empilé dans votre front-end.

**Votre back-end**

```javascript
// Step 1: Extract the data from the Stripe API response
const data = stripeApiResponse.data;

// Step 2: Create a dictionary to store the processed data
const processedData = {};

// Step 3: Iterate through the data and organize it by date and model
data.forEach(point => {
  const date = new Date(point.bucket_start_time * 1000).toISOString().split('T')[0];
  const model = point.dimensions.model;
  const value = point.bucket_value;

  if (!processedData[date]) {
    processedData[date] = {};
  }

  processedData[date][model] = value;
});

// Step 4: Create a list of unique models and sort them
const models = [...new Set(data.map(point => point.dimensions.model))].sort();

// Step 5: Prepare the data for charting
const chartData = [];
Object.keys(processedData).sort().forEach(date => {
  const dataPoint = { date };
  let cumulativeValue = 0;

  models.forEach(model => {
    const value = processedData[date][model] || 0;
    dataPoint[`${model}_start`] = cumulativeValue;
    cumulativeValue += value;
    dataPoint[`${model}_end`] = cumulativeValue;
    dataPoint[model] = value; // For simple stacked charts
  });

  chartData.push(dataPoint);
});

// Return chart data for front end chart library usage
return chartData;
```

**Votre front-end**

```javascript
// Step 1: Fetch usage chart data from your back end
const chartData = await fetch('/api/customer_usage/:customer_id').then(r => r.json());

// Step 2: Extract unique models from the chart data
const models = Object.keys(chartData[0]).filter(key =>
  key !== 'date' && !key.endsWith('_start') && !key.endsWith('_end')
);

// Step 3: Use the chart data to create your stacked bar chart
// Example using D3 or Recharts:
createStackedChart({
  data: chartData.map(point => ({
    date: point.date,
    'gpt-4': point['gpt-4'] || 0,
    'gpt-3.5-turbo': point['gpt-3.5-turbo'] || 0
  })),
  stackKeys: models,
  xKey: 'date',
  title: 'Daily API Usage by Model'
});
```

### Limites de débit

L’API Meter Usage Analytics a sa propre limite d’appels de 100&nbsp;requêtes par seconde et par compte, qui est distincte des limites d’appels globales de l’API Stripe. Si vous dépassez cette limite, l’API renvoie un code d’état `429 Too Many Requests`.

### Granularité de l’horodatage des événements

L’API d’analyse de la consommation effective tronque les horodatages des événements à 15&nbsp;minutes près. Par exemple, un événement dont l’`event_timestamp` est `08:42:15` est sauvegardé dans notre base de données d’analyse avec un horodatage de`08:30:00`.

## Bonnes pratiques

### Gérez l’actualisation des données

Les données d’utilisation peuvent présenter un léger retard. Vous pouvez utiliser le champ `data_refreshed_at` dans la réponse pour comprendre l’actualisation des données. Tenez également compte de cette latence lorsque vous créez des dashboards ou des alertes en temps réel.

### Personnaliser vos requêtes

Suivez ces bonnes pratiques&nbsp;:

- Utilisez les valeurs `value_grouping_window` appropriées pour équilibrer la granularité avec les performances.
- Appliquez `dimension_filters` pour réduire le volume de données lorsque vous n’avez besoin que de segments spécifiques.
- Interrogez plusieurs compteurs dans une même requête lors de l’analyse des habitudes d’utilisation associées.

### Limites de dimension des données

Pour éviter des réponses trop longues, les limites suivantes s’appliquent par mètre&nbsp;:

- Un maximum de 5 `meters`
- Un maximum de 2&nbsp;`dimension_group_by_keys`
- Un maximum de 10&nbsp;`dimension_filters`
- Un maximum de 3 `tenant_filters`

### Gérer les erreurs

L’API renvoie des codes d’état HTTP standard et des réponses d’erreur structurées&nbsp;:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_time_range",
    "message": "Param start_time should not be greater than end_time"
  }
}
```