Skip to main content
GET
/
v1
/
brief
/
batch
Batch Brief
curl --request GET \
  --url https://api.shoal.xyz/v1/brief/batch \
  --header 'Authorization: Bearer <token>'
The batch brief endpoint is designed for AI agents and dashboards that monitor multiple organizations. Instead of making 2N calls (N radar + N signal), make 1 call for up to 25 organizations.
Batch brief is a higher-tier endpoint. Use /v1/brief for single-organization workflows when batch access is not available on your plan.

​
Query Parameters

ParameterTypeRequiredDescription
idsstringYesComma-separated organization IDs (max 25)
sincestringYesISO 8601 timestamp — only events after this time
limitintegerNoMax events per type per org (default 5, max 10)
compactbooleanNoOmit evidence, bullets, owners, and participants (legacy compatibility fields are also omitted)

​
Request

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

​
Response (200)

{
  "organizations": [
    {
      "organizationId": 526,
      "label": "Ethereum",
      "radar": [...],
      "signal": [...],
      "counts": { "radar": 3, "signal": 2 }
    },
    {
      "organizationId": 765,
      "label": "Solana",
      "radar": [...],
      "signal": [...],
      "counts": { "radar": 1, "signal": 4 }
    },
    {
      "organizationId": 99999,
      "label": null,
      "error": "Organization not found",
      "radar": [],
      "signal": [],
      "counts": { "radar": 0, "signal": 0 }
    }
  ]
}

​
Errors

StatusErrorCause
400ids parameter is requiredMissing org IDs
400No valid organization IDs providedAll IDs unparseable
400Maximum 25 organization IDs per batch requestToo many IDs
400since parameter is requiredMissing time filter
Invalid IDs within the batch return inline errors (not a 404), so one bad ID doesn’t fail the whole request. Batch brief event objects follow the same canonical event contract as Radar, Signal, and Search:
  • summary
  • bullets
  • owners
  • participants
  • evidence
  • latestEvidenceTimestamp
  • significance
Legacy fields remain available as compatibility aliases during the transition.

​
Agent Usage Pattern

Python
import requests, os

API_KEY = os.environ["SHOAL_API_KEY"]
PORTFOLIO = "526,765,1024,2048,4096"

# One call for the entire portfolio
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")