Skip to main content
GET
/
v1
/
observability
/
metrics
Get Observability Metrics
curl --request GET \
  --url https://api.truthlocks.com/v1/observability/metrics \
  --header 'X-API-Key: <api-key>'
{
  "metrics": [
    {
      "name": "<string>",
      "values": [
        {
          "timestamp": "2023-11-07T05:31:56Z",
          "value": 123
        }
      ]
    }
  ]
}
Returns aggregated observability metrics for the machine-identity service within the specified time range. Metrics are pre-computed and bucketed by the requested granularity, enabling efficient dashboard queries and SLA reporting. Use this endpoint to power operational dashboards, monitor service health, track agent activity trends, and generate compliance reports.

​
Authentication

​
X-API-Key
string
required
API key with metrics:read scope. Alternatively, pass a Bearer JWT token in the Authorization header.
​
X-Tenant-ID
string
required
Tenant identifier for multi-tenant isolation.

​
Query Parameters

​
from
string
required
Start of the time range in ISO 8601 format (e.g. 2026-04-06T00:00:00Z).
​
to
string
required
End of the time range in ISO 8601 format (e.g. 2026-04-06T23:59:59Z).
​
granularity
string
Aggregation granularity. Must be one of: hour, day, week. Defaults to hour.

​
Response

​
from
string
Start of the queried time range (ISO 8601).
​
to
string
End of the queried time range (ISO 8601).
​
granularity
string
Aggregation granularity used.
​
event_counts
object
Counts per event type within the time range. Each key is an event type (e.g. orchestration.completed), each value is the total count.
​
latencies
object
Latency percentiles in milliseconds for key operations: - orchestration_p50 (number) — Median orchestration duration - orchestration_p95 (number) — 95th percentile orchestration duration - orchestration_p99 (number) — 99th percentile orchestration duration - guardrail_check_p50 (number) — Median guardrail check latency - guardrail_check_p95 (number) — 95th percentile guardrail check latency - guardrail_check_p99 (number) — 99th percentile guardrail check latency
​
error_rate
number
Percentage of events with error severity across all event types. Range: 0.0 to 100.0.
​
active_agents
integer
Number of unique agents that emitted at least one event during the time range.
​
total_orchestrations
integer
Total number of orchestrations started during the time range.
​
total_cost_cents
number
Total accumulated LLM inference cost in US cents across all orchestrations.
​
buckets
array
Time-series array of metric buckets. Each bucket contains timestamp, event_counts, error_rate, and active_agents for the bucket’s time window.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Query Parameters

​
agent_id
string<uuid>

Filter by agent

​
metric_names
string

Comma-separated metric names (e.g. invocations,errors,latency_p99)

​
from
string<date-time>

Start of time range (ISO 8601)

​
to
string<date-time>

End of time range (ISO 8601)

​
interval
enum<string>
default:1h

Aggregation interval

Available options:
1m,
5m,
15m,
1h,
6h,
1d

Response

Metrics data

​
metrics
object[]