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

# Get Entity Research

> List research and commentary-classified entity content for one Shoal entity

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

| Parameter | Type    | Required | Description                                                                       |
| --------- | ------- | -------- | --------------------------------------------------------------------------------- |
| `since`   | string  | No       | ISO 8601 timestamp; defaults to the last 30 days and cannot be older than 30 days |
| `limit`   | integer | No       | Max results (default 25, max 25)                                                  |
| `offset`  | integer | No       | Offset for the first page only (max 250)                                          |
| `cursor`  | string  | No       | Shoal cursor for keyset pagination                                                |

## Request

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

## Response (200)

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