> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Metrics

> Retrieve aggregated service metrics including event counts, latency percentiles, and error rates.

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

<ParamField header="X-API-Key" type="string" required>
  API key with `metrics:read` scope. Alternatively, pass a Bearer JWT token in
  the `Authorization` header.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier for multi-tenant isolation.
</ParamField>

### Query Parameters

<ParamField query="from" type="string" required>
  Start of the time range in ISO 8601 format (e.g. `2026-04-06T00:00:00Z`).
</ParamField>

<ParamField query="to" type="string" required>
  End of the time range in ISO 8601 format (e.g. `2026-04-06T23:59:59Z`).
</ParamField>

<ParamField query="granularity" type="string">
  Aggregation granularity. Must be one of: `hour`, `day`, `week`. Defaults to
  `hour`.
</ParamField>

### Response

<ResponseField name="from" type="string">
  Start of the queried time range (ISO 8601).
</ResponseField>

<ResponseField name="to" type="string">
  End of the queried time range (ISO 8601).
</ResponseField>

<ResponseField name="granularity" type="string">
  Aggregation granularity used.
</ResponseField>

<ResponseField name="event_counts" type="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.
</ResponseField>

<ResponseField name="latencies" type="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
</ResponseField>

<ResponseField name="error_rate" type="number">
  Percentage of events with `error` severity across all event types. Range:
  `0.0` to `100.0`.
</ResponseField>

<ResponseField name="active_agents" type="integer">
  Number of unique agents that emitted at least one event during the time range.
</ResponseField>

<ResponseField name="total_orchestrations" type="integer">
  Total number of orchestrations started during the time range.
</ResponseField>

<ResponseField name="total_cost_cents" type="number">
  Total accumulated LLM inference cost in US cents across all orchestrations.
</ResponseField>

<ResponseField name="buckets" type="array">
  Time-series array of metric buckets. Each bucket contains `timestamp`,
  `event_counts`, `error_rate`, and `active_agents` for the bucket's time
  window.
</ResponseField>


## OpenAPI

````yaml mint-openapi.yaml GET /v1/metrics
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/metrics:
    get:
      tags:
        - Machine Identity
      summary: Get Observability Metrics
      description: |
        Returns time-series metrics for agent activity. Supports multiple metric
        names and configurable time intervals for aggregation.
      operationId: maip.observability.metrics.get
      parameters:
        - name: agent_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by agent
        - name: metric_names
          in: query
          schema:
            type: string
          description: Comma-separated metric names (e.g. invocations,errors,latency_p99)
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: Start of time range (ISO 8601)
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: End of time range (ISO 8601)
        - name: interval
          in: query
          schema:
            type: string
            enum:
              - 1m
              - 5m
              - 15m
              - 1h
              - 6h
              - 1d
            default: 1h
          description: Aggregation interval
      responses:
        '200':
          description: Metrics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipMetrics'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipMetrics:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              values:
                type: array
                items:
                  type: object
                  properties:
                    timestamp:
                      type: string
                      format: date-time
                    value:
                      type: number
                      format: float
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Human-readable error message
        http_status:
          type: integer
          description: HTTP status code
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying (for rate limits)
        details:
          type: object
          description: Additional error context
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````