Event history

Read the recorded history of a signal, beacon, spec, pull request or ticket, including events on the items it flowed into.

nima records an event each time something happens to a signal, beacon, spec, pull request or tracker ticket: a signal joins a beacon, a beacon is promoted, a spec finishes, a pull request merges. The event history route reads that record for one item, newest first. It returns ids, types and timestamps, never the text behind them.

On for every workspace. The history route does not depend on the workspace's triggersEnabled setting: nima records events whether or not watches are on.

Event history operations at a glance

Method	Path	Scope	MCP tool
`GET`	`/v1/events`	`signals:read`	`get_history`

Paths are relative to https://api.getnima.io. Every call carries Authorization: Bearer <your key>. See Authentication and Scopes and permissions. The MCP tool is documented on Pipeline MCP tools.

Read the event history of one item

GET/v1/events

scopesignals:readMCP toolget_history

The recorded events of one signal, beacon, spec, pull request or ticket, newest first. The list includes events on the things the item flowed into: ask for a signal and you also get the events of its beacon, its spec and its pull request. Those rows carry viaLineage: true. Each event stores the items upstream of it at the moment it is recorded, so an event on a beacon recorded before your signal joined that beacon is not in the signal's history.

subjectKindenumrequired

What subjectId refers to: signal, beacon, spec, pr or ticket. Any other value is rejected with 400. Events are matched on subjectId; subjectKind only selects the title, so a mismatched kind returns the events with title: null.

subjectIduuidrequired

The id of the item, as returned by the signal, beacon, spec or delivery routes. A malformed id is rejected with 400.

limitinteger

Maximum number of events. Defaults to 50. Accepts 1 to 200; a value outside that range is rejected with 400.

The route has no pagination: to see more than 200 events you cannot page back. Events are ordered by time, newest first.

The history is org-wide, not limited to what the caller watches, which is why it needs signals:read and not the personal subscriptions:read scope. It never returns another workspace's events: the query carries your workspace id.

Response fields

subjectKindstring

Echo of the request.

subjectIduuid

Echo of the request.

titlestring | null

nima's own title for the item, never the underlying text: the source of a signal (for example Slack signal), the beacon title, the spec title, PR #n for a pull request, or the issue key and summary for a ticket. null when the item no longer exists or belongs to another workspace.

eventsarray

The events, newest first, described below.

Each element of events:

iduuid

The event id.

typestring

One of the event types, for example beacon.promoted.

subjectKindstring

The kind of item the event happened to. It differs from your request when viaLineage is true.

subjectIduuid

The item the event happened to.

viaLineageboolean

true when the event is on a downstream item rather than the one you asked for. false when subjectId is the id you sent.

actorKindstring

Who caused the event: user, system or integration.

occurredAtstring

When it happened, ISO 8601 in UTC.

The response has no payload field. Event payloads can carry a question's text or a person's reason for holding a beacon, so this route does not repeat them. Read the item itself (a signal, beacon or spec) for its content.

Response 200

{
  "subjectKind": "signal",
  "subjectId": "6f1c2d9a-0b7e-4c53-9a41-2e8d5b7f3a10",
  "title": "Slack signal",
  "events": [
    {
      "id": "b3f0c9d2-5a1e-4e0f-8c7a-91d4e6a2f5b8",
      "type": "spec.shipped",
      "subjectKind": "spec",
      "subjectId": "0d8e4a17-3c2b-4f6e-b1a9-7c5d2e8f4a63",
      "viaLineage": true,
      "actorKind": "integration",
      "occurredAt": "2026-09-28T14:02:11.000Z"
    },
    {
      "id": "e71a5c08-9b3d-4a2f-86e1-0c4f7d9b2a35",
      "type": "pr.linked_to_spec",
      "subjectKind": "pr",
      "subjectId": "a2c94f6b-1d80-4b7e-93a5-5e6f8c0d1b47",
      "viaLineage": true,
      "actorKind": "integration",
      "occurredAt": "2026-09-25T09:40:52.000Z"
    },
    {
      "id": "48d2f1a6-7e5c-4b93-a0d8-3f1e9c6b7a24",
      "type": "signal.attached_to_beacon",
      "subjectKind": "signal",
      "subjectId": "6f1c2d9a-0b7e-4c53-9a41-2e8d5b7f3a10",
      "viaLineage": false,
      "actorKind": "system",
      "occurredAt": "2026-09-22T16:15:03.000Z"
    }
  ]
}

Event types in history

The type field of an event history row is one of nima's 16 event types, the same fixed catalog that watches react to. The full table, with the item each type belongs to and whether it is material, is under Watch event types. The catalog itself is served by GET /v1/triggers/event-types and the list_event_types tool.

A row's subjectKind follows the type: signal.* events belong to signals, beacon.* to beacons, spec.* to specs, pr.* to pull requests and ticket.* to tracker tickets. One exception: spec.generation_failed belongs to the beacon, because a failed run has no spec yet.

Errors from the event history route

Status	When
`400`	`subjectKind` is not one of the five kinds, `subjectId` is not a UUID, or `limit` is outside 1 to 200.
`401`	No valid bearer token.
`403`	The key or token lacks `signals:read`, or the caller lacks read permission in the workspace.

An id that matches nothing in your workspace is not an error: the route answers 200 with title: null and an empty events array. See Errors for the response shape.