Skip to main content
GET
/
v1
/
entities
/
:id
/
research
Get Entity Research
curl --request GET \
  --url https://api.shoal.xyz/v1/entities/:id/research \
  --header 'Authorization: Bearer <token>'
Returns recent research-oriented items attached to one canonical Shoal entity. This v1 surface is a projection over Shoal’s existing classified event stream. It is meant to accumulate research, commentary, and analysis around the canonical entity without requiring full historical backfill first.

​
Path Parameters

  • id (integer, required)

​
Query Parameters

ParameterTypeRequiredDescription
sincestringNoISO 8601 timestamp; defaults to the last 30 days and cannot be older than 30 days
limitintegerNoMax results (default 25, max 25)
offsetintegerNoOffset for the first page only (max 250)
cursorstringNoShoal cursor for keyset pagination

​
Request

cURL
curl -X GET "https://api.shoal.xyz/v1/entities/23151/research?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (200)

{
  "entity": {
    "id": 23151,
    "canonicalName": "Ethereum",
    "displayName": "Ethereum",
    "entityType": "project",
    "status": "active",
    "aliases": ["Ethereum Foundation", "ETH"],
    "references": []
  },
  "limit": 10,
  "since": "2026-03-12T00:00:00Z",
  "next_cursor": "eyJ0cyI6IjIwMjYtMDQtMTFUMTc6MjA6MDBaIiwiaWQiOjE4MjQsImNvbnRleHQiOnsic2luY2UiOiIyMDI2LTAzLTEyVDAwOjAwOjAwWiIsInNjb3BlIjoiZW50aXRpZXMvMjMxNTEvcmVzZWFyY2gifX0",
  "data": [
    {
      "id": 1940,
      "title": "Ethereum staking economics research note",
      "eventCategory": "analysis",
      "eventSubcategory": "research_report",
      "summary": "A research note analyzed staking participation, validator concentration, and long-term token economics.",
      "bullets": [
        "Validator concentration remains a focus area.",
        "Staking participation continues to support network security."
      ],
      "owners": [
        {
          "id": 23151,
          "label": "Ethereum",
          "type": "project",
          "aliases": ["ETH"]
        }
      ],
      "participants": [],
      "evidence": [
        {
          "id": 778890,
          "content": "Ethereum staking economics research note...",
          "url": "https://example.com/post",
          "timestamp": "2026-04-10T12:05:00Z"
        }
      ],
      "latestEvidenceTimestamp": "2026-04-10T12:05:00Z",
      "significance": 6.2,
      "sourceType": "classified_event",
      "contentType": "research",
      "eventSurface": "radar"
    }
  ]
}

​
Notes

  • This route is an operational surface.
  • It is sourced from entity-linked events that Shoal already classifies as research, commentary, or analysis content.
  • Shoal-authored long-form reports can be layered into this route later without changing the route contract.

​
Errors

  • 400 if id is missing
  • 400 if since is older than 30 days
  • 404 if the entity does not exist
  • 500 on internal server error