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.

​
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 posts, bulletSummary, eventOwner, eventParticipants

​
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 }
    }
  ],
  "creditCost": 9
}

​
Credit Cost

3 credits per organization ID in the request. The creditCost field in the response tells you exactly what was charged, so agents can self-budget.
OrgsCreditsMonthly (3x/day)
5151,350
10302,700
25756,750
50 (2 calls)15013,500

​
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.

​
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")

print(f"Credits used: {data['creditCost']}")