Skip to main content
GET
/
v1
/
entities
/
:id
/
media
Get Entity Media
curl --request GET \
  --url https://api.shoal.xyz/v1/entities/:id/media \
  --header 'Authorization: Bearer <token>'
Returns recent media-classified items attached to one canonical Shoal entity. This v1 surface is a projection over Shoal’s existing classified event stream. It does not depend on the separate beta media system, and it is intentionally bounded to recent, entity-linked content.

​
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/media?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": "eyJ0cyI6IjIwMjYtMDQtMTFUMTc6MjA6MDBaIiwiaWQiOjE4MjQsImNvbnRleHQiOnsic2luY2UiOiIyMDI2LTAzLTEyVDAwOjAwOjAwWiIsInNjb3BlIjoiZW50aXRpZXMvMjMxNTEvbWVkaWEifX0",
  "data": [
    {
      "id": 1824,
      "title": "Ethereum documentary release highlights ecosystem growth",
      "eventCategory": "analysis",
      "eventSubcategory": "media_content",
      "summary": "A long-form media feature highlighted Ethereum's ecosystem growth and institutional interest.",
      "bullets": [
        "The feature covered ecosystem maturity.",
        "Institutional interest was a central theme."
      ],
      "owners": [
        {
          "id": 23151,
          "label": "Ethereum",
          "type": "project",
          "aliases": ["ETH"]
        }
      ],
      "participants": [],
      "evidence": [
        {
          "id": 778210,
          "content": "Ethereum documentary release...",
          "url": "https://example.com/post",
          "timestamp": "2026-04-11T17:20:00Z"
        }
      ],
      "latestEvidenceTimestamp": "2026-04-11T17:20:00Z",
      "significance": 5.4,
      "sourceType": "classified_event",
      "contentType": "media",
      "eventSurface": "signal"
    }
  ]
}

​
Notes

  • This route is an operational surface.
  • It is sourced from entity-linked events that Shoal already classifies as media-oriented content.
  • Direct partner media and richer publisher-level metadata are a later source layer, not the v1 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