Skip to main content
GET
/
v1
/
brief
Get Brief
curl --request GET \
  --url https://api.shoal.xyz/v1/brief \
  --header 'Authorization: Bearer <token>'

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.

Returns radar and signal events in a single response, eliminating the need for two separate API calls.
Brief endpoints are available only on plans that include the Shoal brief surface.

​
Query Parameters

ParameterTypeRequiredDescription
idintegerYesOrganization ID
sincestringYesISO 8601 timestamp — only events after this time
limitintegerNoMax events per type (default 5, max 20)
compactbooleanNoOmit evidence, bullets, owners, and participants (legacy compatibility fields are also omitted)

​
Request

cURL
curl -X GET "https://api.shoal.xyz/v1/brief?id=526&since=2026-02-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Compact Request

cURL
curl -X GET "https://api.shoal.xyz/v1/brief?id=526&since=2026-02-01T00:00:00Z&compact=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (200)

{
  "organizationId": 526,
  "label": "Ethereum",
  "radar": [
    {
      "id": 42,
      "title": "Ethereum Foundation announces grants program",
      "eventCategory": "funding",
      "summary": "...",
      "latestEvidenceTimestamp": "2026-02-15T10:30:00Z",
      "globalSummary": "...",
      "latestPostTimestamp": "2026-02-15T10:30:00Z"
    }
  ],
  "signal": [
    {
      "id": 99,
      "title": "Ethereum Layer 2 adoption surge",
      "eventCategory": "technology",
      "significance": 8.5,
      "summary": "...",
      "latestEvidenceTimestamp": "2026-02-14T08:00:00Z",
      "signal": 8.5,
      "globalSummary": "...",
      "latestPostTimestamp": "2026-02-14T08:00:00Z"
    }
  ],
  "counts": {
    "radar": 1,
    "signal": 1
  }
}
New integrations should build against the canonical event aliases shown above. Legacy fields such as globalSummary, latestPostTimestamp, and signal are still returned as compatibility fields during the transition.

​
Errors

StatusErrorCause
400id parameter is requiredMissing org ID
400since parameter is requiredMissing time filter
404Organization not foundInvalid org ID