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

# Get observations

> List observations recorded for company domains since a time.

`get_observations` is an authenticated Jolts MCP tool. [Connect your assistant](/mcp-overview) first.

Give it company domains and a time. It returns every observation recorded
after that time for those companies, oldest first, with the same evidence fields as a company
search. It reads the existing dataset only: no provider or AI call runs inside the request.
Domains with no coverage yet are reported as `not_found` and queued for a scheduled refresh where
a permitted source exists.

## Arguments

| Argument      | Type         | Requirement                                                     |
| ------------- | ------------ | --------------------------------------------------------------- |
| `domains`     | String array | 1–100 company hostnames                                         |
| `since`       | String       | ISO 8601 time; only observations recorded after it are returned |
| `kinds`       | String array | Optional observation kinds to include                           |
| `limit`       | Integer      | 1–100, default 25, bounded by the plan's result cap             |
| `cursor`      | String       | Continuation token from a previous page                         |
| `request_key` | String       | Required unless supplied through the `Idempotency-Key` header   |

## Example call

This is the `params` object of a JSON-RPC `tools/call`, not a complete HTTP request.

```json theme={null}
{
  "name": "get_observations",
  "arguments": {
    "domains": ["northstar.example.test", "missing.example.test"],
    "since": "2026-09-27T00:00:00Z",
    "request_key": "observations-2026-09-28"
  }
}
```

These hostnames are fictional. A daily agent keeps the `observed_at` of the last change it
handled and passes it as the next `since`. A completed call consumes one request unit and one
delivered unit per distinct company with changes; empty results consume no company units.

## Read the response

| Field              | What it means                                     | What to do                                                 |
| ------------------ | ------------------------------------------------- | ---------------------------------------------------------- |
| `observations`     | Observations recorded after `since`, oldest first | Act on the fact and cite its evidence                      |
| `domains[].status` | `found` or `not_found` per hostname               | `not_found` means no coverage yet, not an inactive company |
| `next_cursor`      | Continuation token, or `null`                     | Request another page with a new request key                |
| `as_of`            | The frozen read time for this page set            | Use the newest `observed_at` as the next `since`           |

For the complete result fields, see the [HTTP observation lookup](/api-reference/observations/get-observations).

## Related

* [Choose a tool](/mcp-tools)
* [Look up known companies](/tools/get-companies)