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

# Search Events

> Search Shoal events by topic, organization, protocol, or narrative

Search is the best starting point for most integrations. It lets you search across Radar and Signal event history without resolving an organization ID first.

Search results use the same canonical event contract as Radar, Signal, Brief, and webhook payloads. New integrations should build against:

* `summary`
* `bullets`
* `owners`
* `participants`
* `evidence`
* `latestEvidenceTimestamp`
* `significance`
* `matchedVia`
* `matchType`
* `matchRank`

Legacy compatibility fields may still appear during the transition:

* `globalSummary`
* `bulletSummary`
* `eventOwner`
* `eventParticipants`
* `posts`
* `latestPostTimestamp`
* `signal`

## Query Parameters

| Parameter | Type    | Required | Description                                            |
| --------- | ------- | -------- | ------------------------------------------------------ |
| `query`   | string  | Yes\*    | Search text                                            |
| `q`       | string  | Yes\*    | Compatibility alias for `query`                        |
| `limit`   | integer | No       | Max results (default 10, max 20)                       |
| `since`   | string  | No       | ISO 8601 timestamp to restrict results to newer events |

\* Either `query` or `q` is required.

### Request

```bash cURL theme={null}
curl -X GET "https://api.shoal.xyz/v1/search?query=ethereum%20foundation&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json theme={null}
{
  "query": "ethereum foundation",
  "limit": 5,
  "data": [
    {
      "id": 1824,
      "title": "Ethereum Foundation expands research grants",
      "eventCategory": "funding",
      "eventSubcategory": "grants",
      "summary": "The Ethereum Foundation expanded its research grants program with new funding for protocol research and ecosystem tooling.",
      "bullets": [
        "Funding expanded for protocol research.",
        "Ecosystem tooling is included in the new grants pool."
      ],
      "owners": [
        {
          "id": 23151,
          "label": "Ethereum Foundation",
          "type": "project",
          "aliases": ["EF"]
        }
      ],
      "participants": [],
      "evidence": [
        {
          "id": 778210,
          "content": "Ethereum Foundation expands research grants...",
          "url": "https://example.com/post",
          "timestamp": "2026-04-11T17:20:00Z"
        }
      ],
      "latestEvidenceTimestamp": "2026-04-11T17:20:00Z",
      "significance": 6.8,
      "matchedVia": "semantic",
      "matchType": "event",
      "matchRank": 0.97,
      "globalSummary": "The Ethereum Foundation expanded its research grants program with new funding for protocol research and ecosystem tooling.",
      "bulletSummary": [
        "Funding expanded for protocol research.",
        "Ecosystem tooling is included in the new grants pool."
      ],
      "eventOwner": [
        {
          "id": 23151,
          "label": "Ethereum Foundation",
          "type": "project",
          "aliases": ["EF"]
        }
      ],
      "eventParticipants": [],
      "posts": [
        {
          "id": 778210,
          "content": "Ethereum Foundation expands research grants...",
          "url": "https://example.com/post",
          "timestamp": "2026-04-11T17:20:00Z"
        }
      ],
      "latestPostTimestamp": "2026-04-11T17:20:00Z",
      "signal": 6.8
    }
  ]
}
```

### Notes

* Search is the recommended first request for evaluation and prototypes.
* Use `/v1/entities/byName` when you need a stable Shoal entity id for repeated monitoring and traversal.
* Use Radar or Signal feed endpoints only when you already know you need a premium feed surface.
* Treat `organizations/byOrganizationName` as a compatibility route for older integrations.

### Errors

* 400 if `query`/`q` is missing
* 500 on internal server error