Metrics API

Retrieve metrics and monitoring data for branches

The Metrics API allows you to retrieve performance and monitoring metrics for your database branches, including CPU, memory, and disk usage. All endpoints require authentication via API key or OIDC.

Authentication

All endpoints require authentication. You can authenticate using:

API Key: Include your API key in the Authorization header: Authorization: Bearer <your-api-key>
OIDC: Use OIDC tokens for authentication

Required scopes for different operations:

metrics:read: Access to metrics and monitoring data

Get branch metrics

Retrieves metrics for a specific branch over a time period.

POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics

Summary

Returns time-series metrics data for CPU, memory, and disk usage across branch instances. Supports multiple aggregation types and can filter by specific instances.

Path parameters

Parameter	Type	Required	Description
organizationID	string	Yes	Unique identifier for the organization
projectID	string	Yes	Unique identifier for the project
branchID	string	Yes	Unique identifier for the branch

Request body

{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-01T23:59:59Z",
  "metric": "cpu",
  "instances": ["inst_123", "inst_456"],
  "aggregations": ["avg", "max", "min"]
}

Request body parameters

Parameter	Type	Required	Description
start	string (date-time)	Yes	Start time for the metrics query
end	string (date-time)	Yes	End time for the metrics query
metric	string	Yes	Metric name to query. Options: `cpu`, `memory`, `disk`
instances	array	Yes	List of instance IDs to query
aggregations	array	Yes	List of aggregations to apply. Options: `avg`, `max`, `min`

Response

Status: 200 OK

{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-01T23:59:59Z",
  "metric": "cpu",
  "unit": "percentage",
  "series": [
    {
      "instance": "inst_123",
      "aggregation": "avg",
      "data": [
        {
          "timestamp": "2024-01-01T00:00:00Z",
          "value": 25.5
        },
        {
          "timestamp": "2024-01-01T01:00:00Z",
          "value": 30.2
        }
      ]
    },
    {
      "instance": "inst_123",
      "aggregation": "max",
      "data": [
        {
          "timestamp": "2024-01-01T00:00:00Z",
          "value": 45.0
        },
        {
          "timestamp": "2024-01-01T01:00:00Z",
          "value": 52.1
        }
      ]
    }
  ]
}

Response schema

Field	Type	Description
start	string (date-time)	Start time of the metrics period
end	string (date-time)	End time of the metrics period
metric	string	The metric type that was queried
unit	string	The unit of measurement (percentage, bytes, ms, etc.)
series	array	Array of metric series, one per instance and aggregation

Metric types

cpu: CPU usage percentage
memory: Memory usage in bytes
disk: Disk usage in bytes

Aggregation types

avg: Average value over the time interval
max: Maximum value over the time interval
min: Minimum value over the time interval

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "id": "error_identifier",
  "message": "Human-readable error message explaining the issue"
}

Common error responses

Status	Error Type	Description
400	GenericError	Request was malformed or contained invalid parameters
401	AuthorizationError	Authentication failed or is missing
404	GenericError	Requested organization, project, or branch does not exist
5XX	GenericError	Server error occurred

Schema Reference

Core Data Models

BranchMetrics

Time-series metrics data for monitoring branch performance.

Field	Type	Required	Description
start	string (date-time)	Yes	Start time of the metrics period
end	string (date-time)	Yes	End time of the metrics period
metric	string	Yes	The metric type that was queried
unit	string	Yes	The unit of measurement (percentage, bytes, ms, etc.)
series	array	Yes	Array of metric series, one per instance and aggregation

BranchMetricsRequest

Parameters for querying branch metrics over a time period.

Field	Type	Required	Description
start	string (date-time)	Yes	Start time for the metrics query
end	string (date-time)	Yes	End time for the metrics query
metric	string	Yes	Metric name to query. Options: `cpu`, `memory`, `disk`
instances	array	Yes	List of instance IDs to query
aggregations	array	Yes	List of aggregations to apply. Options: `avg`, `max`, `min`

MetricSeries

Individual metric series data for a specific instance and aggregation.

Field	Type	Required	Description
instance	string	Yes	Instance ID for this metric series
aggregation	string	Yes	Aggregation type applied (avg, max, min)
data	array	Yes	Array of timestamp-value pairs

MetricDataPoint

Individual data point in a metric series.

Field	Type	Required	Description
timestamp	string (date-time)	Yes	Timestamp for this data point
value	number	Yes	Metric value at this timestamp

Usage Examples

Monitor CPU usage over time

curl -X POST "https://api.xata.tech/organizations/org_123/projects/proj_456/branches/br_789/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T23:59:59Z",
    "metric": "cpu",
    "instances": ["inst_123"],
    "aggregations": ["avg", "max"]
  }'

Check memory usage for multiple instances

curl -X POST "https://api.xata.tech/organizations/org_123/projects/proj_456/branches/br_789/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T23:59:59Z",
    "metric": "memory",
    "instances": ["inst_123", "inst_456"],
    "aggregations": ["avg"]
  }'

Branches

Automations