Custom | OpenMeter

Custom exporters allow you to export aggregated metered usage to any destination that supports webhooks. You can configure the following:

How frequently to run the export (minute, hour, day)
Which meters to export
Filter and grouping
Destination webhook URL

#Configuring Syncs

OpenMeter Cloud has a UI to configure usage syncs.

Create Usage Sync

#Via API

Setting up a sync via API that reports the daily usage looks as:

curl -X POST https://openmeter.cloud/api/v1/reports \
  -H 'Content-Type: application/cloudevents+json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  --data-raw '
{
  "slug": "my_usage_report",
  "meterIdOrSlug": "ai_prompt_tokens",
  "type": "webhook",
  "schedule": {
    "interval": "1d",
    "startAt": "2023-01-01T00:00:00.000Z"
  },
  "query": {
    "groupBy": ["model"]
  },
  "endpoint": {
    "url": "https://mydomain/api/webhooks"
  },
  "filter": {
    "usage": {
      "$gt": 100
    }
  }
}'

Note how we use the optional filter property here only to report usage greater than 100.

Filtering is possible on both subject and usage. Available filters are: $gt, $gte, $lt, $lte, $eq, $ne, $in and $nin. You can filter for specific subjects as filter: { subject: { $in: ["customer-1", "customer-2"] } }.

#Example Webhook Sync Payload

Usage syncs are delivered as JSON payloads to your webhook endpoint. We deliver a separate webhook for each subject. The usage array contains the aggregated usage for the subject. If the report defines a group by the usage property, it will contain a separate entry for each group.

{
  "report": {
    "slug": "my_usage_report"
  },
  "usage": [
    {
      "subject": "customer-1",
      "value": 500,
      "groupBy": {
        "model": "gpt-4"
      },
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-02T00:00:00Z"
    },
    {
      "subject": "customer-1",
      "value": 10000,
      "groupBy": {
        "model": "gpt-3-turbo"
      },
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-02T00:00:00Z"
    }
  ],
  "query": {
    "from": "2023-01-01T00:00:00Z",
    "to": "2023-01-02T00:00:00Z",
    "subject": "customer-1",
    "groupBy": ["model"]
  },
  "meter": {
    "id": "01H98E5HHJ8K0AYXQKM3EKAVYG",
    "slug": "ai_prompt_tokens",
    "description": "OpenAI Prompt Tokens",
    "aggregation": "SUM",
    "windowSize": "MINUTE",
    "eventType": "tokens",
    "valueProperty": "$.prompt_tokens",
    "groupBy": {
      "model": "$.model"
    }
  }
}

#Consuming Webhooks

To consume OpenMeter webhooks, you need to verify the webhook signature and process the payload. Check out the Consuming Webhooks guide for more details.

#Debugging Syncs

You can debug syncs in the OpenMeter Cloud UI by checking the sync status and logs. The sync status shows the last run time, the status of the last run, and if any errors occurred.