> ## 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.