Overview

The MetaRouter Metrics API provides programmatic access to event-level metrics from your in-cluster infrastructure. These metrics are sourced directly from your MetaRouter deployment’s metrics database and reflect actual event counts, including delivered, dropped and filtered events, across dimensions such as write_key, event_name and integration.

Use this API to:

Monitor event delivery performance
Feed aggregated metrics into your internal observability stack (e.g. Datadog, New Relic, etc.)
Set up automated jobs for pipeline health monitoring and alerting

Authentication

To access the Metrics API, you must authenticate using a Bearer token generated via MetaRouter’s Control API.

🔐 Steps to Authenticate

Obtain your Client ID and Secret

MetaRouter will provide you with the Client ID and Client Secret.

Use Control API to get an access token

curl --request POST --url https://<your_cluster_endpoint>/v1.1/oauth/token --header 'Content-Type: application/json'      --data '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "audience": "https://control.metarouter.io"
}'

Extract the access_token from the response and use it in subsequent requests to the Metrics API:
```
Authorization: Bearer <your_access_token>
```

Note: Tokens expire after 24 hours

Accessing the Metrics API

Endpoint

Use the following endpoint to access Event Delivery metrics:

POST https://<your_cluster_endpoint>/v1.1/analytics/event_delivery

You can also access Event Ingestion metrics with the following endpoint:

POST https://<your_cluster_endpoint>/v1.1/analytics/event_ingestion

Required Headers

Header	Value
`Authorization`	`Bearer <your_access_token>`
`Content-Type`	`application/json`

Request Body Format

{
  "start": "2025-09-14T00:00:00.000Z",
  "end": "2025-09-14T23:59:59.999Z",
  "dimensions": ["event_name", "write_key", "integration", "reason"]
}

Parameters

Field	Type	Required	Description
`start`	string	✅	Start of the time window (UTC ISO 8601)
`end`	string	✅	End of the time window (UTC ISO 8601)
`dimensions`	string[]	✅	One or more group-by fields, consisting of `event_name`, `write_key`, `integration` and `reason`

Note: reason refers to filtering reason, if applicable. Reasons include playbook filter or compliance filter. The reason dimension is only available for Event Delivery metrics.

Sample Response

"start": "2025-09-14T00:00:00Z",
    "end": "2025-09-14T23:59:59.999Z",
    "totalDelivered": "100000",
    "totalErrors": "100",
    "totalFiltered": "150",
    "counts": [
        {
            "success": "100000",
            "errors": "100",
            "filtered": "150",
            "dimensions": {
                "write_key": "sample_write_key"
            }
        },
    ]

Response Fields

Field	Description
`start`	Start of the time window (UTC ISO 8601)
`end`	End of the time window (UTC ISO 8601)
`totalDelivered`	Total events delivered within the specified timeframe
`totalErrors`	Total events not sent due to an error
`totalFiltered`	Total events filtered from the event stream due to playbook, pipeline or compliance filters
`counts`	Object containing counts of events (`success`, `errors`, `filtered`) and dimensions included with the query

Best Practices

Use UTC timestamps in ISO 8601 format with Z (Zulu) suffix
Query data in short intervals (e.g. 5–15 minutes) to avoid large responses
Handle token expiration gracefully — either refresh on error or re-auth periodically
Apply tags when pushing to observability tools (e.g. write_key, reason, cluster)