Skip to main content
GET
/
v1
/
search
Search Events
curl --request GET \
  --url https://api.shoal.xyz/v1/search \
  --header 'Authorization: Bearer <token>'
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

ParameterTypeRequiredDescription
querystringYes*Search text
qstringYes*Compatibility alias for query
limitintegerNoMax results (default 10, max 20)
sincestringNoISO 8601 timestamp to restrict results to newer events
* Either query or q is required.

​
Request

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

​
Response (200)

{
  "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