openapi: 3.0.0 info: title: Xata API Keys Metrics API description: Xata API version: '1.0' contact: name: help@xata.io servers: - url: https://api.xata.tech description: Xata API tags: - name: Metrics description: Operations for retrieving observability metrics for a branch x-displayName: Metrics paths: /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics: post: operationId: branchMetrics summary: Retrieve branch metrics description: Returns time-series data for one or more metrics of a branch. parameters: - name: organizationID in: path required: true schema: $ref: '#/components/schemas/OrganizationID' - name: projectID in: path required: true schema: type: string - name: branchID in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BranchMetricsRequest' responses: '200': description: Metrics for a branch content: application/json: schema: $ref: '#/components/schemas/BranchMetrics' '400': $ref: '#/components/responses/GenericError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/GenericError' 5XX: description: Unexpected Error default: description: Unexpected Error security: - xata: - metrics:read tags: - Metrics components: schemas: BranchMetricResult: description: Time-series for a single metric. type: object properties: metric: description: Name of the queried metric. type: string unit: description: Unit of the metric (percentage, bytes, ms, etc.) type: string series: type: array items: $ref: '#/components/schemas/MetricSeries' required: - metric - unit - series MetricSeries: description: The metric series type: object properties: instanceID: description: ID of the instance type: string aggregation: description: The aggregation used to generate this time-series type: string enum: - avg - max - min values: type: array items: type: object properties: timestamp: type: string format: date-time value: type: number required: - timestamp - value required: - instanceID - aggregation - values OrganizationID: title: OrganizationID type: string pattern: '[a-zA-Z0-9_-~:]+' x-oapi-codegen-extra-tags: validate: identifier BranchMetricsRequest: type: object properties: start: description: Start time type: string format: date-time end: description: End time type: string format: date-time metrics: description: List of metric names to query. type: array items: $ref: '#/components/schemas/BranchMetricName' maxItems: 15 minItems: 1 instances: description: List of instance IDs to query type: array items: type: string aggregations: description: List of aggregations to get, this is how the data-points within the interval are aggregated. Each one will generate a separate time-series per metric in the response. type: array items: type: string enum: - avg - max - min required: - start - end - metrics - aggregations BranchMetricName: description: Name of a branch metric exposed by the API. type: string enum: - cpu - memory - disk - connections_active - connections_idle - network_ingress - network_egress - iops_read - iops_write - latency_read - latency_write - throughput_read - throughput_write - wal_sync_time - replication_lag_time BranchMetrics: description: A collection of metrics (cpu, memory, disk,...) for each of the instances of a branch type: object properties: start: type: string format: date-time end: type: string format: date-time results: description: One entry per requested metric, in the order the metrics were requested. type: array items: $ref: '#/components/schemas/BranchMetricResult' required: - start - end - results responses: GenericError: description: Generic error response for most error conditions content: application/json: schema: type: object properties: id: description: Error identifier for tracking and debugging type: string message: description: Human-readable error message explaining the issue type: string required: - message AuthorizationError: description: Error response when authentication or authorization fails content: application/json: schema: type: object properties: id: description: Error identifier for tracking and debugging type: string message: description: Human-readable error message explaining the authentication or authorization issue type: string required: - message securitySchemes: oidc: type: openIdConnect openIdConnectUrl: https://auth.xata.io/realms/xata/.well-known/openid-configuration apiKey: type: apiKey in: header name: Authorization description: 'API key authentication using Bearer token format: Bearer ' xata: type: oauth2 flows: implicit: authorizationUrl: https://auth.xata.io/realms/xata/protocol/openid-connect/auth scopes: org:read: Read organization information org:write: Create and modify organizations keys:read: Read API keys keys:write: Create and manage API keys project:read: Read project information project:write: Create and modify projects branch:read: Read branch information branch:write: Create and modify branches metrics:read: Read metrics data logs:read: Read logs data credentials:read: Read credentials credentials:write: Rotate credentials marketplace:write: Register with cloud marketplaces branchConnectionString: type: apiKey in: header name: Connection-String description: Branch PostgreSQL connection string (`postgres://user:pass@{branch}.{region}.xata.tech/db`), including the embedded password. The hostname selects the target branch, region, and endpoint type (the `-rw`/`-ro` suffix, see `EndpointType`), and must match the request host. Obtain it from the Xata dashboard or the control-plane API. This is the only credential the gateway accepts; the control-plane API key (Bearer token) is rejected here. For the WebSocket endpoint (`GET /v2`) the same connection string is conveyed via the PostgreSQL startup message instead of this header. externalDocs: url: https://xata.io/docs/api x-tagGroups: - name: Authentication API tags: - Organizations - Users - API Keys - Marketplace - Billing - Webhooks - name: Gateway API tags: - Gateway - name: Projects API tags: - Projects Webhooks - Projects - Branches - GitHub App - Metrics - Logs