> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/observability-api.md).

# Observability API

Count, group, and chart your solution's Record data from code with Solution Metrics.

The Observability API provides Solution Metrics: values, breakdowns, and trends calculated from your tenant's Record data. Use it from solution code that powers dashboards, reports, or alerts. For example, scheduled code can count each day's new Records and raise an alert above a threshold.

The API returns data, not charts. For ready-made dashboards in the Console, see [Metrics](https://docs.contextual.io/documentation-and-resources/tenants/monitoring/metrics.md).

## What you can do

* Calculate single values, tables, and pie-chart slices, such as Records by status.
* Build time series by minute, hour, day, week, or month, and histograms of numeric fields.
* Query an Object Type's Records, attachment metadata, or Record change history. Change history needs [Audit Trail](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/features.md) on the Object Type.
* List the fields found in a collection's recent data.

The reference also lists `POST /metrics` and `POST /metrics/ai`, which the Console uses for its runtime and AI Gateway dashboards. `POST /logs` and `POST /traces` are not implemented and return `501`.

## Base URL and reference

* **API base URL:** `https://observability.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Observability API reference](https://observability.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://observability.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). The hostname identifies your tenant, so the `x-org-id` header is optional. If you send it, it must match the hostname.

The OpenAPI document uses a relative server, so set the API base URL as the server when you import it into an API client or AI tool.

## Authentication and permissions

Send an access token from a tenant API Key in the `Authorization: Bearer <access-token>` header. To get one, see [Get an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token).

Set the key's permissions on its [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions), under **Object data & action execution**. Each query needs **Read** for the data it covers:

| Query                                                                                                                                              | Required permission                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Records of one Object Type (`coll_name`: `native-object:<type-id>`)                                                                                | **Read** in that Object Type's row                |
| Attachment metadata (`contextual:files`) or Record change history (`contextual:native-object-instances-history`), limited to specific Object Types | **Read** in the row of each of those Object Types |
| Attachment metadata or Record change history without an Object Type limit; any other collection; or any `coll_name_prefix` query                   | **Read** in the **All Object Types** row          |

`<type-id>` is the Object Type's ID, as used in its Native Object API path, such as `customers`. **Read** in the **All Object Types** row covers every query above.

To limit attachment metadata or change history to specific Object Types, set `ref.typeId`, or add a `where` condition with `=` or `IN` on `ref.typeId` (attachments) or `data.typeId` (change history). For per-type access, a type condition in `where` must use the default `AND` mode; `OR` filters do not by themselves establish the required Object Type restriction. Schema discovery takes only `coll_name`, so it needs wildcard read for attachment metadata and Record change history. When the key cannot read a collection, the API returns `403`.

## Request and response details

* Metric queries use `POST /metrics/solution`. Schema discovery uses `POST /metrics/solution/schema/discover` with the body `{"coll_name": "<collection>"}` and returns `db_name`, `coll_name`, `total_paths`, and a `schema` list of field paths and types. Both only read data.
* Each metric query needs a source, a time range, and at least one `select` entry. Set the source with `coll_name`, such as `native-object:<type-id>`, or `coll_name_prefix`, such as `native-object:` for all Object Types. For the time range, send `last`, such as `-7d` or `all`, or both `from` and `to`.
* By default, time ranges and buckets use the time of each Record change. To use creation dates, set `time_field` to `createdAt`.
* Set `output` to `value`, `table` (the default), `pie`, `timeseries`, or `histogram`. The response contains `output`, `data`, and `meta`. `data` is an object for `value` and an array of rows otherwise.
* Record collections such as `native-object:<type-id>` keep captured versions of each Record. Without `dedup`, a Record can count more than once, and earlier versions of deleted Records can still count. For current counts or status breakdowns, use `dedup`. With `"dedup": true`, change-time queries select each Record's latest captured version within the time window; `createdAt` queries include later updates to Records created in that window. `dedup` also leaves out Records whose latest version is a delete. For current totals or status breakdowns across all captured Records, also set `"last": "all"`. Change history has one entry per change, so `dedup` does not change it.
* Results include only the data captured for your tenant. See [Interpreting Solution Data](https://docs.contextual.io/documentation-and-resources/tenants/monitoring/metrics.md#interpreting-solution-data).
* An invalid query returns `400` with a `message` and an `errors` list. A query that exceeds time or data limits also returns `400`; narrow the time range or source.

## Example request

This request counts the captured Records of one Object Type that were created in the last 30 days, leaving out deleted Records:

```bash
curl --request POST "https://observability.<tenant-id>.my.contextual.io/api/v1/metrics/solution" \
  --header "Authorization: Bearer <access-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "coll_name": "native-object:<type-id>",
    "last": "-30d",
    "time_field": "createdAt",
    "dedup": true,
    "output": "value",
    "select": [{ "agg": "count", "alias": "created" }]
  }'
```

Replace `<tenant-id>`, `<access-token>`, and `<type-id>` as described above. A successful response returns `200` with the count in `data.created`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/observability-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
