Ingest events

curl --request POST \
  --url https://api.metronome.com/v1/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "transaction_id": "2021-01-01T00:00:00Z_cluster42",
    "customer_id": "team@example.com",
    "event_type": "heartbeat",
    "timestamp": "2021-01-01T00:00:00Z",
    "properties": {
      "cluster_id": "42",
      "cpu_seconds": 60,
      "region": "Europe"
    }
  }
]
'

import requests

url = "https://api.metronome.com/v1/ingest"

payload = [
    {
        "transaction_id": "2021-01-01T00:00:00Z_cluster42",
        "customer_id": "team@example.com",
        "event_type": "heartbeat",
        "timestamp": "2021-01-01T00:00:00Z",
        "properties": {
            "cluster_id": "42",
            "cpu_seconds": 60,
            "region": "Europe"
        }
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      transaction_id: '2021-01-01T00:00:00Z_cluster42',
      customer_id: 'team@example.com',
      event_type: 'heartbeat',
      timestamp: '2021-01-01T00:00:00Z',
      properties: {cluster_id: '42', cpu_seconds: 60, region: 'Europe'}
    }
  ])
};

fetch('https://api.metronome.com/v1/ingest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.metronome.com/v1/ingest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'transaction_id' => '2021-01-01T00:00:00Z_cluster42',
        'customer_id' => 'team@example.com',
        'event_type' => 'heartbeat',
        'timestamp' => '2021-01-01T00:00:00Z',
        'properties' => [
                'cluster_id' => '42',
                'cpu_seconds' => 60,
                'region' => 'Europe'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metronome.com/v1/ingest"

	payload := strings.NewReader("[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v1/ingest")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v1/ingest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

Usage

Ingest events

The ingest endpoint is the primary method for sending usage events to Metronome, serving as the foundation for all billing calculations in your usage-based pricing model. This high-throughput endpoint is designed for real-time streaming ingestion, supports backdating 34 days, and is built to handle mission-critical usage data with enterprise-grade reliability. Metronome supports 100,000 events per second without requiring pre-aggregation or rollups and can scale up from there. See the Send usage events guide to learn more about usage events.

Use this endpoint to:

Create a customer usage pipeline into Metronome that drives billable metrics, credit drawdown, and invoicing. Track customer behavior, resource consumption, and feature usage

What happens when you send events:

Events are validated and processed in real-time
Events are matched to customers using customer IDs or customer ingest aliases
Events are matched to billable metrics and are immediately available for usage and spend calculations

Usage guidelines:

Historical events can be backdated up to 34 days and will immediately impact live customer spend
Duplicate events are automatically detected and ignored (34-day deduplication window)

Event structure:

Usage events are simple JSON objects designed for flexibility and ease of integration:

{
  "transaction_id": "2021-01-01T00:00:00Z_cluster42",
  "customer_id": "team@example.com",
  "event_type": "api_request",
  "timestamp": "2021-01-01T00:00:00Z",
  "properties": {
    "endpoint": "/v1/users",
    "method": "POST",
    "response_time_ms": 45,
    "region": "us-west-2"
  }
}

Learn more about usage event structure definitions.

Transaction ID

The transaction_id serves as your idempotency key, ensuring events are processed exactly once. Metronome maintains a 34-day deduplication window - significantly longer than typical 12-hour windows - enabling robust backfill scenarios without duplicate billing.

Best Practices:
- Use UUIDs for one-time events: uuid4()
- For heartbeat events, use deterministic IDs
- Include enough context to avoid collisions across different event sources

Customer ID

Identifies which customer should be billed for this usage. Supports two identification methods:

Metronome Customer ID: The UUID returned when creating a customer
Ingest Alias: Your system’s identifier (email, account number, etc.)

Ingest aliases enable seamless integration without requiring ID mapping, and customers can have multiple aliases for flexibility.

Event Type:

Categorizes the event type for billable metric matching. Choose descriptive names that aligns with the product surface area.

Properties:

Flexible metadata also used to match billable metrics or to be used to serve as group keys to create multiple pricing dimensions or breakdown costs by novel properties for end customers or internal finance teams measuring underlying COGs.

POST

ingest

Ingest events

curl --request POST \
  --url https://api.metronome.com/v1/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "transaction_id": "2021-01-01T00:00:00Z_cluster42",
    "customer_id": "team@example.com",
    "event_type": "heartbeat",
    "timestamp": "2021-01-01T00:00:00Z",
    "properties": {
      "cluster_id": "42",
      "cpu_seconds": 60,
      "region": "Europe"
    }
  }
]
'

import requests

url = "https://api.metronome.com/v1/ingest"

payload = [
    {
        "transaction_id": "2021-01-01T00:00:00Z_cluster42",
        "customer_id": "team@example.com",
        "event_type": "heartbeat",
        "timestamp": "2021-01-01T00:00:00Z",
        "properties": {
            "cluster_id": "42",
            "cpu_seconds": 60,
            "region": "Europe"
        }
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      transaction_id: '2021-01-01T00:00:00Z_cluster42',
      customer_id: 'team@example.com',
      event_type: 'heartbeat',
      timestamp: '2021-01-01T00:00:00Z',
      properties: {cluster_id: '42', cpu_seconds: 60, region: 'Europe'}
    }
  ])
};

fetch('https://api.metronome.com/v1/ingest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.metronome.com/v1/ingest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'transaction_id' => '2021-01-01T00:00:00Z_cluster42',
        'customer_id' => 'team@example.com',
        'event_type' => 'heartbeat',
        'timestamp' => '2021-01-01T00:00:00Z',
        'properties' => [
                'cluster_id' => '42',
                'cpu_seconds' => 60,
                'region' => 'Europe'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metronome.com/v1/ingest"

	payload := strings.NewReader("[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v1/ingest")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v1/ingest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n    \"customer_id\": \"team@example.com\",\n    \"event_type\": \"heartbeat\",\n    \"timestamp\": \"2021-01-01T00:00:00Z\",\n    \"properties\": {\n      \"cluster_id\": \"42\",\n      \"cpu_seconds\": 60,\n      \"region\": \"Europe\"\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Required array length: 1 - 100 elements

transaction_id

string

required

Required string length: 1 - 128

customer_id

string

required

Minimum string length: 1

event_type

string

required

Minimum string length: 1

timestamp

string

required

RFC 3339 formatted

properties

object

Response

200

Success

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Ingest events

Use this endpoint to:

What happens when you send events:

Usage guidelines:

Event structure:

Transaction ID

Customer ID

Event Type:

Properties:

Authorizations

Body

Response