Read

Pull trending content, search posts, and monitor feeds from any platform through one endpoint.

POST/v1/social/read

Example request

import socialrouter

client = socialrouter.Client("sr_your_api_key")

trends = client.read(
    platform="reddit",
    source="r/wallstreetbets",
    sort="hot",
    limit=25
)

for post in trends.items:
    print(f"{post.author}: {post.text[:80]}")
    print(f"  {post.engagement.total:,} engagement")

Request body

Field	Type	Description
platformrequired	string	Target platform: x, reddit, instagram, tiktok, discord, telegram, youtube, threads.
source	string	Platform-specific source. e.g. "r/wallstreetbets" for Reddit, "@username" for X, channel ID for YouTube.
query	string	Search query. Cannot be used together with `source`.
sort	string	Sort order: hot, new, top, engagement. Default: hot.
limit	integer	Number of results to return. Min 1, max 100. Default: 25.
filters	object	Optional filters: min_engagement, media_only, time_range.

Example body

{
  "platform": "reddit",
  "source": "r/wallstreetbets",
  "sort": "hot",
  "limit": 25,
  "filters": {
    "min_engagement": 100,
    "media_only": true,
    "time_range": "24h"
  }
}

Response

Field	Type	Description
items	array	Array of content items matching the query.
items[].id	string	Unique platform-native ID for the item.
items[].platform	string	Source platform identifier.
items[].author	string	Original poster handle, prefixed with platform convention (u/, @).
items[].text	string	Post body text. Mentions and hashtags preserved as-is.
items[].media_url	string \| null	URL to attached media. Null if text-only.
items[].media_type	string \| null	image, video, gif, or null.
items[].engagement	object	Platform-specific engagement metrics, normalized.
items[].published_at	string	ISO 8601 timestamp of original post.
items[].url	string	Direct link to the post on the source platform.
meta	object	Request metadata including credits consumed.

Example response

{
  "items": [
    {
      "id": "abc123",
      "platform": "reddit",
      "author": "u/deepvalue",
      "text": "GME to the moon 🚀",
      "media_url": "https://i.redd.it/example.jpg",
      "media_type": "image",
      "engagement": {
        "upvotes": 15234,
        "comments": 892,
        "awards": 47,
        "total": 16173
      },
      "published_at": "2026-04-25T10:30:00Z",
      "url": "https://reddit.com/r/wallstreetbets/..."
    }
  ],
  "meta": {
    "platform": "reddit",
    "source": "r/wallstreetbets",
    "count": 25,
    "credits_used": 0.025
  }
}