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

# Batch Brief

> Get combined radar and signal events for multiple organizations in one call

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.

<Note>
  Batch brief is a higher-tier endpoint. Use `/v1/brief` for single-organization workflows when batch access is not available on your plan.
</Note>

## Query Parameters

| Parameter | Type    | Required | Description                                                                                             |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `ids`     | string  | Yes      | Comma-separated organization IDs (max 25)                                                               |
| `since`   | string  | Yes      | ISO 8601 timestamp — only events after this time                                                        |
| `limit`   | integer | No       | Max events per type per org (default 5, max 10)                                                         |
| `compact` | boolean | No       | Omit `evidence`, `bullets`, `owners`, and `participants` (legacy compatibility fields are also omitted) |

### Request

```bash cURL theme={null}
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)

```json theme={null}
{
  "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

| Status | Error                                         | Cause               |
| ------ | --------------------------------------------- | ------------------- |
| 400    | `ids` parameter is required                   | Missing org IDs     |
| 400    | No valid organization IDs provided            | All IDs unparseable |
| 400    | Maximum 25 organization IDs per batch request | Too many IDs        |
| 400    | `since` parameter is required                 | Missing 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 Python theme={null}
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")
```