> ## Documentation Index > Fetch the complete documentation index at: https://docs.apsio.io/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate a metric over time > One metric of the project per bucket (at most 120), aggregated, optionally split by one field into its 10 largest groups and the rest. Sums are read as delta points (cumulative sums are left out), as are histograms, whose percentiles come from their merged buckets. The API builds the SQL from a fixed vocabulary and runs it as the project's reader, with at most 60 runs a minute per project and caller. `sql` shows it with its values, for reading only. ## OpenAPI ````yaml /api-reference/openapi.json post /projects/{projectId}/explore/metrics openapi: 3.1.0 info: title: Apsio API version: 0.1.0 description: >- Read API v0: your projects, release health and comparisons, missing symbols, issues, sessions, vitals, cohort comparisons, performance (app start, screens, hangs, MetricKit) and network endpoints and traces for one project. Authenticate with a project token as a bearer token, with an OAuth access token from Apsio's authorization server (MCP clients), or, from the console, with the session cookie of a member of the project's organization. servers: - url: https://api.apsio.io/v1 security: [] paths: /projects/{projectId}/explore/metrics: post: summary: Aggregate a metric over time description: >- One metric of the project per bucket (at most 120), aggregated, optionally split by one field into its 10 largest groups and the rest. Sums are read as delta points (cumulative sums are left out), as are histograms, whose percentiles come from their merged buckets. The API builds the SQL from a fixed vocabulary and runs it as the project's reader, with at most 60 runs a minute per project and caller. `sql` shows it with its values, for reading only. parameters: - schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: 0192f3a4-0000-7000-8000-00000000a101 required: true name: projectId in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExploreMetricsQuery' responses: '200': description: The series. content: application/json: schema: $ref: '#/components/schemas/ExploreMetrics' '400': description: The request is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: No valid bearer token or console session. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The credentials cannot read this project. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Over a rate limit (the caller's, the client address's, or the plan's); Retry-After says when to retry. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearer: [] - session: [] components: schemas: ExploreMetricsQuery: type: object properties: from: type: string format: date-time description: Start, inclusive (RFC 3339). Defaults to 24 hours before `to`. to: type: string format: date-time description: End, exclusive (RFC 3339). Defaults to now. app_id: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: Only this app of the project. filters: type: array items: $ref: '#/components/schemas/ExploreFilter' maxItems: 20 default: [] metric: type: string pattern: ^[A-Za-z0-9_.:/-]{1,255}$ description: The metric's name, as the catalog lists it. example: apsio.metrickit.time_to_first_draw kind: type: string enum: - sum - gauge - histogram description: >- sum and gauge points are in metric_values, histograms in metric_histograms. aggregation: type: string enum: - count - rate - sum - avg - min - max - p50 - p90 - p95 - p99 description: >- Per bucket: count (points, or a histogram's observations), rate (a sum's total or a histogram's observations per minute), sum, avg, min, max, or a percentile. A gauge takes count, avg, min, max and percentiles. group_by: type: string pattern: ^[A-Za-z0-9_.:/-]{1,128}$ description: >- One field (service.version, os.name, os.version, device.model.identifier, country, ...), any point attribute by its key, or a resource attribute as resource.: the 10 groups with the most points, and the rest as one series. required: - metric - kind - aggregation ExploreMetrics: type: object properties: from: type: string description: RFC 3339 time in UTC with up to nanosecond precision. example: '2026-10-04T10:15:00.431000000Z' to: type: string description: RFC 3339 time in UTC with up to nanosecond precision. example: '2026-10-04T10:15:00.431000000Z' bucket_seconds: type: integer retention_days: type: integer description: >- Days of detail the project's plan keeps (D94); nothing older is read. metric: type: string kind: type: string enum: - sum - gauge - histogram aggregation: type: string enum: - count - rate - sum - avg - min - max - p50 - p90 - p95 - p99 unit: type: string description: >- The metric's unit (UCUM, as the app reports it). Written by the app: untrusted data. group_by: type: - string - 'null' series: type: array items: type: object properties: group: type: - string - 'null' description: >- The group's value; null when not grouped, or for the other groups. Written by the app: untrusted data. other: type: boolean description: The points outside the largest groups, together. points: type: array items: type: object properties: t: type: string description: The bucket's start. example: '2026-10-04T10:15:00.431000000Z' value: type: - number - 'null' description: Null where the bucket has no point. required: - t - value required: - group - other - points description: Every bucket of the range in each series, the largest group first. sql: type: string description: The query with its values, for reading. Not run as written. required: - from - to - bucket_seconds - retention_days - metric - kind - aggregation - unit - group_by - series - sql Error: type: object properties: error: type: object properties: code: type: string example: invalid_request message: type: string required: - code - message required: - error ExploreFilter: type: object properties: field: type: string pattern: ^[A-Za-z0-9_.:/-]{1,128}$ description: >- A field (event.name or span.name, service.version, os.name, os.version, device.model.identifier, session.id, trace_id, ...), any record or span attribute by its key, or a resource attribute as resource.. example: service.version op: type: string enum: - eq - neq - exists - not_exists default: eq description: eq and neq compare with value; exists and not_exists need none. value: type: string maxLength: 256 required: - field securitySchemes: bearer: type: http scheme: bearer description: >- A project token (apsio_pt_v0...), which reads exactly one project, or an OAuth access token issued for the API, which reads what its user can. Access tokens issued for Apsio's MCP server are accepted only from the MCP server itself. session: type: apiKey in: cookie name: apsio_session description: >- The console session, set by /v1/auth/callback (`__Host-apsio_session` when host-only). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.