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

# Get Timeline by Entity ID

> Get a recent merged event timeline for a single Shoal entity

Timeline v1 is Shoal's first explicit historical-query surface. It is narrower
than a full replay product by design:

* one entity at a time
* recent window only
* evidence-backed events
* ordered by newest evidence

Timeline results use the same canonical event contract as Search, Radar,
Signal, Brief, and webhook payloads. Build against:

* `summary`
* `bullets`
* `owners`
* `participants`
* `evidence`
* `latestEvidenceTimestamp`
* `significance`

Legacy compatibility fields may still appear during the transition:

* `globalSummary`
* `bulletSummary`
* `eventOwner`
* `eventParticipants`
* `posts`
* `latestPostTimestamp`
* `signal`

## Query Parameters

| Parameter | Type    | Required | Description                                         |
| --------- | ------- | -------- | --------------------------------------------------- |
| `id`      | integer | Yes      | Canonical Shoal entity ID                           |
| `since`   | string  | Yes      | ISO 8601 timestamp; must be within the last 30 days |
| `limit`   | integer | No       | Max results (default 25, max 25)                    |
| `offset`  | integer | No       | Offset for the first page only (max 250)            |
| `cursor`  | string  | No       | Shoal cursor for keyset pagination                  |

## Request

```bash cURL theme={null}
curl -X GET "https://api.shoal.xyz/v1/timeline/byOrganizationId?id=23151&since=2026-04-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response (200)

```json theme={null}
{
  "entity": {
    "id": 23151,
    "label": "Ethereum Foundation",
    "type": "project",
    "aliases": ["EF"]
  },
  "organization": {
    "id": 23151,
    "label": "Ethereum Foundation",
    "type": "project",
    "aliases": ["EF"]
  },
  "limit": 10,
  "since": "2026-04-01T00:00:00Z",
  "next_cursor": "eyJ0cyI6IjIwMjYtMDQtMTFUMTc6MjA6MDBaIiwiaWQiOjE4MjQsImNvbnRleHQiOnsic2luY2UiOiIyMDI2LTA0LTAxVDAwOjAwOjAwWiIsInNjb3BlIjoidGltZWxpbmUvYnlPcmdhbml6YXRpb25JZDoyMzE1MSJ9fQ",
  "data": [
    {
      "id": 1824,
      "title": "Ethereum Foundation expands research grants",
      "eventCategory": "funding",
      "eventSubcategory": "grants",
      "summary": "The Ethereum Foundation expanded its research grants program with new funding for protocol research and ecosystem tooling.",
      "bullets": [
        "Funding expanded for protocol research.",
        "Ecosystem tooling is included in the new grants pool."
      ],
      "owners": [
        {
          "id": 23151,
          "label": "Ethereum Foundation",
          "type": "project",
          "aliases": ["EF"]
        }
      ],
      "participants": [],
      "evidence": [
        {
          "id": 778210,
          "content": "Ethereum Foundation expands research grants...",
          "url": "https://example.com/post",
          "timestamp": "2026-04-11T17:20:00Z"
        }
      ],
      "latestEvidenceTimestamp": "2026-04-11T17:20:00Z",
      "significance": 6.8
    }
  ]
}
```

## Notes

* Timeline v1 is designed for scoped investigation and automation, not full replay.
* `entity` is the canonical top-level traversal object. `organization` remains in the payload as a compatibility field during the transition.
* Use `/v1/entities/byName` first if you need to resolve a human-readable name into a stable Shoal entity id. `organizations/byOrganizationName` remains available as a compatibility route.
* Use `cursor` for subsequent pages after the first request.
* Timeline v1 is an operational surface. Global replay or bulk history export should be treated as a separate premium product surface.

## Errors

* 400 if `id` is missing
* 400 if `since` is missing or older than 30 days
* 404 if the entity does not exist
* 500 on internal server error