Search Events

curl --request GET \
  --url https://api.shoal.xyz/v1/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.shoal.xyz/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shoal.xyz/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoal.xyz/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shoal.xyz/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

Search Events

curl --request GET \
  --url https://api.shoal.xyz/v1/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.shoal.xyz/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shoal.xyz/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoal.xyz/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shoal.xyz/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

Core

Brief

Entities

Organizations (Compatibility)

Timeline

Replay

Radar

Signal

Export

Webhooks

Search Events

Query Parameters

Request

Response (200)

Notes

Errors

​Query Parameters

​Request

​Response (200)

​Notes

​Errors

Query Parameters

Request

Response (200)

Notes

Errors