Skip to main content

​
List Organizations

cURL
curl -X GET "https://api.shoal.xyz/v1/organizations/all?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
import os, requests
API_KEY = os.environ.get("SHOAL_API_KEY", "YOUR_API_KEY")
r = requests.get(
    "https://api.shoal.xyz/v1/organizations/all",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 5},
)
print(r.json())
JavaScript
const API_KEY = process.env.SHOAL_API_KEY || 'YOUR_API_KEY';
const url = new URL('https://api.shoal.xyz/v1/organizations/all');
url.searchParams.set('limit', 5);
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
console.log(await res.json());

​
Get Recent Radar Events

The since parameter is required on /radar/all and /signal/all.
cURL
curl -X GET "https://api.shoal.xyz/v1/radar/all?since=2026-02-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
requests.get(
  "https://api.shoal.xyz/v1/radar/all",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"since": "2026-02-01T00:00:00Z", "limit": 10}
)
JavaScript
const radarRes = await fetch(
  'https://api.shoal.xyz/v1/radar/all?since=2026-02-01T00:00:00Z&limit=10',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

​
Radar by Organization ID

cURL
curl -X GET "https://api.shoal.xyz/v1/radar/byOrganizationId?id=526" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
requests.get(
  "https://api.shoal.xyz/v1/radar/byOrganizationId",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"id": 526}
)
JavaScript
const res2 = await fetch(
  'https://api.shoal.xyz/v1/radar/byOrganizationId?id=526',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

​
Signal by Category

cURL
curl -X GET "https://api.shoal.xyz/v1/signal/byCategory?category=partnership" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
requests.get(
  "https://api.shoal.xyz/v1/signal/byCategory",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"category": "partnership"}
)
JavaScript
const res3 = await fetch(
  'https://api.shoal.xyz/v1/signal/byCategory?category=partnership',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

​
Poll for New Signals

Python
import time

cursor = "2026-02-01T00:00:00Z"

while True:
    r = requests.get(
        "https://api.shoal.xyz/v1/signal/all",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"since": cursor},
    )
    data = r.json()["data"]
    if data:
        cursor = data[0]["latestPostTimestamp"]
        for event in data:
            print(event["title"], event["signal"])
    time.sleep(60)

​
Batch Brief (Agent Workflow)

Monitor an entire portfolio in one call:
cURL
curl -X GET "https://api.shoal.xyz/v1/brief/batch?ids=526,765,1024&since=2026-02-28T00:00:00Z&compact=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
PORTFOLIO = "526,765,1024,2048"

r = requests.get(
    "https://api.shoal.xyz/v1/brief/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"ids": PORTFOLIO, "since": "2026-02-28T00:00:00Z", "compact": "true"},
)

data = r.json()
for org in data["organizations"]:
    if org["counts"]["signal"] > 0:
        print(f"{org['label']}: {org['counts']['signal']} new signals")
print(f"Credits used: {data['creditCost']}")
JavaScript
const portfolio = '526,765,1024,2048';
const briefRes = await fetch(
  `https://api.shoal.xyz/v1/brief/batch?ids=${portfolio}&since=2026-02-28T00:00:00Z&compact=true`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { organizations, creditCost } = await briefRes.json();
organizations
  .filter(org => org.counts.signal > 0)
  .forEach(org => console.log(`${org.label}: ${org.counts.signal} new signals`));
console.log(`Credits used: ${creditCost}`);

​
Check Your Usage

cURL
curl -X GET "https://api.shoal.xyz/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"