Get Timeline by Entity ID

curl --request GET \
  --url https://api.shoal.xyz/v1/timeline/byOrganizationId \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.shoal.xyz/v1/timeline/byOrganizationId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shoal.xyz/v1/timeline/byOrganizationId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoal.xyz/v1/timeline/byOrganizationId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shoal.xyz/v1/timeline/byOrganizationId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

timeline

byOrganizationId

Get Timeline by Entity ID

curl --request GET \
  --url https://api.shoal.xyz/v1/timeline/byOrganizationId \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.shoal.xyz/v1/timeline/byOrganizationId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shoal.xyz/v1/timeline/byOrganizationId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoal.xyz/v1/timeline/byOrganizationId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shoal.xyz/v1/timeline/byOrganizationId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

Core

Brief

Entities

Organizations (Compatibility)

Timeline

Replay

Radar

Signal

Export

Webhooks

Get Timeline by Entity ID

Query Parameters

Request

Response (200)

Notes

Errors

​Query Parameters

​Request

​Response (200)

​Notes

​Errors

Query Parameters

Request

Response (200)

Notes

Errors