Skip to main content

​
Metrics API

Track gauges, counters, distributions, and sets via the API.

​
Track Metric

POST /api/v1/metrics

​
Request

curl https://flux.brainzlab.ai/api/v1/metrics \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api.response_time",
    "type": "distribution",
    "value": 145.2,
    "timestamp": "2024-01-15T10:30:00Z",
    "tags": {
      "endpoint": "/users",
      "method": "GET",
      "status": "200"
    }
  }'

​
Parameters

FieldTypeRequiredDescription
namestringYesMetric name
typestringYesgauge, counter, distribution, or set
valuenumber/stringYesMetric value (string for sets)
timestampstringNoISO8601 timestamp (defaults to now)
tagsobjectNoIndexed metadata for filtering

​
Metric Types

Gauge - Current value (overwrites previous): 
{ "name": "users.online", "type": "gauge", "value": 234 }
Counter - Incrementing value (summed): 
{ "name": "api.requests", "type": "counter", "value": 1 }
Distribution - Statistical aggregation: 
{ "name": "response_time", "type": "distribution", "value": 145.2 }
Set - Unique count (cardinality): 
{ "name": "daily_active_users", "type": "set", "value": "user_123" }

​
Response

{
  "data": {
    "name": "api.response_time",
    "type": "distribution",
    "value": 145.2,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Batch Track

Send multiple metrics in one request: 
POST /api/v1/metrics/batch

​
Request

curl https://flux.brainzlab.ai/api/v1/metrics/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      { "name": "users.online", "type": "gauge", "value": 234 },
      { "name": "api.requests", "type": "counter", "value": 1 },
      { "name": "response_time", "type": "distribution", "value": 145.2 }
    ]
  }'

​
Response

{
  "data": {
    "accepted": 3,
    "rejected": 0
  }
}

​
List Metrics

Get all metric definitions: 
GET /api/v1/metrics

​
Request

curl "https://flux.brainzlab.ai/api/v1/metrics" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": [
    {
      "name": "api.response_time",
      "type": "distribution",
      "tags": ["endpoint", "method", "status"],
      "first_seen": "2024-01-01T00:00:00Z",
      "last_seen": "2024-01-15T10:30:00Z"
    },
    {
      "name": "users.online",
      "type": "gauge",
      "tags": ["region"],
      "first_seen": "2024-01-01T00:00:00Z",
      "last_seen": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Get Metric

Get a specific metric definition: 
GET /api/v1/metrics/:name

​
Request

curl "https://flux.brainzlab.ai/api/v1/metrics/api.response_time" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": {
    "name": "api.response_time",
    "type": "distribution",
    "tags": ["endpoint", "method", "status"],
    "first_seen": "2024-01-01T00:00:00Z",
    "last_seen": "2024-01-15T10:30:00Z",
    "data_points": 1234567
  }
}

​
Query Metric

Query metric time series: 
GET /api/v1/metrics/:name/query

​
Parameters

ParameterTypeDescription
fromstringStart timestamp (ISO8601)
tostringEnd timestamp (ISO8601)
aggregationstringAggregation function
intervalstringTime bucket (1m, 5m, 1h, 1d)
tags[key]stringFilter by tag value

​
Aggregations by Type

TypeAvailable Aggregations
Gaugelast, avg, min, max
Countersum, rate
Distributionavg, sum, min, max, p50, p90, p95, p99, count
Setcount (cardinality)

​
Request

curl "https://flux.brainzlab.ai/api/v1/metrics/api.response_time/query?\
from=2024-01-15T00:00:00Z&\
to=2024-01-15T23:59:59Z&\
aggregation=p95&\
interval=1h&\
tags[endpoint]=/users" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": {
    "name": "api.response_time",
    "aggregation": "p95",
    "interval": "1h",
    "series": [
      { "timestamp": "2024-01-15T00:00:00Z", "value": 125.3 },
      { "timestamp": "2024-01-15T01:00:00Z", "value": 132.1 },
      { "timestamp": "2024-01-15T02:00:00Z", "value": 118.7 }
    ]
  }
}

​
Multiple Aggregations

Request multiple aggregations at once: 
curl "https://flux.brainzlab.ai/api/v1/metrics/api.response_time/query?\
aggregation=p50,p95,p99&\
interval=1h" \
  -H "Authorization: Bearer sk_live_xxx"

{
  "data": {
    "name": "api.response_time",
    "interval": "1h",
    "series": [
      {
        "timestamp": "2024-01-15T00:00:00Z",
        "p50": 45.2,
        "p95": 125.3,
        "p99": 312.8
      }
    ]
  }
}

​
Group By Tags

curl "https://flux.brainzlab.ai/api/v1/metrics/api.requests/query?\
aggregation=sum&\
interval=1h&\
group_by=tags.endpoint" \
  -H "Authorization: Bearer sk_live_xxx"

{
  "data": {
    "groups": {
      "/users": [
        { "timestamp": "2024-01-15T00:00:00Z", "value": 1234 }
      ],
      "/orders": [
        { "timestamp": "2024-01-15T00:00:00Z", "value": 567 }
      ]
    }
  }
}

​
Combined Batch

Send events and metrics together: 
POST /api/v1/flux/batch

​
Request

curl https://flux.brainzlab.ai/api/v1/flux/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "name": "order.placed", "value": 99.99 }
    ],
    "metrics": [
      { "name": "orders.count", "type": "counter", "value": 1 }
    ]
  }'

​
Response

{
  "data": {
    "events": { "accepted": 1, "rejected": 0 },
    "metrics": { "accepted": 1, "rejected": 0 }
  }
}

​
Rate Limits

  • Single metric: Standard rate limit
  • Batch: 10 requests/minute, up to 500 metrics per request
  • Query: 60 requests/minute

​
Errors

CodeDescription
missing_nameMetric name is required
invalid_typeType must be gauge/counter/distribution/set
invalid_valueValue must be numeric (string for sets)
batch_too_largeBatch exceeds 500 metrics