Skip to main content
GET
/
v1
/
timeline
/
byOrganizationId
Get Timeline by Entity ID
curl --request GET \
  --url https://api.shoal.xyz/v1/timeline/byOrganizationId \
  --header 'Authorization: Bearer <token>'
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

ParameterTypeRequiredDescription
idintegerYesCanonical Shoal entity ID
sincestringYesISO 8601 timestamp; must be within the last 30 days
limitintegerNoMax results (default 25, max 25)
offsetintegerNoOffset for the first page only (max 250)
cursorstringNoShoal cursor for keyset pagination

​
Request

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

{
  "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