Social Monitoring API
Query a unified on-demand feed from Hacker News, Lobsters, and Reddit with durable monitoring checkpoints, plus opt-in X (Twitter) search by keyword, @handle, or trend — and post-detail fetches including body, engagement, and thread context.
Use with the agent-data CLI
Section titled “Use with the agent-data CLI”Inspect every route, parameter, and response schema straight from your agent:
agent-data docs d7ac1bae-c5c2-496b-bcfc-2c984b83ff5bCall any route below by its slug:
agent-data call d7ac1bae-c5c2-496b-bcfc-2c984b83ff5b <route-slug> [--param value ...]Routes
Section titled “Routes”| Route slug | Method & path | Description |
|---|---|---|
get-feed | GET /api/v1/feed | Feed |
get-detail | GET /api/v1/detail/{source}/{item_id} | Detail |
get-linked-content | GET /api/v1/detail/{source}/{item_id}/linked-content | Linked Content |
get-feed
Section titled “get-feed”GET /api/v1/feed
Feed
agent-data call d7ac1bae-c5c2-496b-bcfc-2c984b83ff5b get-feed --source <source> [--subreddit <subreddit>] [--q <q>] [--user elonmusk] [--trend <trend>] [--limit <limit>] [--page_token <page_token>] [--since_token <since_token>]| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
source | query | ”x” | “reddit” | “hackernews” | “lobsters” | yes | Exactly one of hackernews, lobsters, reddit, or x — one source per request. Comma-separated lists and all are rejected. When source=x, also provide exactly one of q, user, or trend. When `source=reddi… |
subreddit | query | string | null | no | Required when source=reddit; rejected otherwise. Format r/<name>. r/all and r/new are rejected. |
q | query | string | null | no | X only (source=x). Keyword or hashtag search; returns the newest tweets matching this query. Provide exactly one of q, user, or trend. Rejected when source does not include x. |
user | query | string | null | no | X only (source=x). A single @handle whose newest tweets to return (e.g. elonmusk); one handle only. This is the only X mode that supports since_token monitoring. Provide exactly one of q, user, or trend. |
trend | query | string | null | no | X only (source=x). A single trend category to surface: one of trending, news, sport, entertainment. Provide exactly one of q, user, or trend. |
limit | query | integer, min: 1, max: 100 | null | no | Return at most this many feed items in the current response. Omit this parameter to use the source-aware route default (20 for x, since it pages at ~20 items per rate-limited op; 100 for the firehose sources). Increas… |
page_token | query | string | null | no | Opaque cursor from a prior response’s meta.next_page_token. Omit on the first request. Reuse only with the same source and subreddit that produced it. |
since_token | query | string | null | no | Fetch only items newer than a previously saved checkpoint by passing the opaque token returned in meta.next_since_token. Omit this parameter when requesting the newest page. Use it for monitoring-style polling rather… |
Full REST reference — parameters, schemas, and curl →
get-detail
Section titled “get-detail”GET /api/v1/detail/{source}/{item_id}
Detail
agent-data call d7ac1bae-c5c2-496b-bcfc-2c984b83ff5b get-detail --source <source> --item_id <item_id> [--subreddit <subreddit>] [--comment_page_token <comment_page_token>] [--comment_max_page_size <comment_max_page_size>]| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
source | path | ”x” | “reddit” | “hackernews” | “lobsters” | yes | The platform that owns the requested item. |
item_id | path | string | yes | Source-native item identifier from a feed item’s item_id field. |
subreddit | query | string | null | no | Required when source=reddit; rejected otherwise. Format r/<name>. r/all and r/new are rejected. |
comment_page_token | query | string | null | no | Opaque cursor from a prior response’s comment_pagination.next_page_token. Paginates top-level comments only. |
comment_max_page_size | query | integer, min: 1, max: 100, default: 100 | no | Top-level comments per page, 1 to 100. Default 100. |
Full REST reference — parameters, schemas, and curl →
get-linked-content
Section titled “get-linked-content”GET /api/v1/detail/{source}/{item_id}/linked-content
Linked Content
agent-data call d7ac1bae-c5c2-496b-bcfc-2c984b83ff5b get-linked-content --source <source> --item_id <item_id> [--subreddit <subreddit>] [--page_token <page_token>] [--max_page_size <max_page_size>]| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
source | path | ”x” | “reddit” | “hackernews” | “lobsters” | yes | The platform that owns the story whose outbound link will be expanded. |
item_id | path | string | yes | Source-native identifier of the story whose linked page to read. |
subreddit | query | string | null | no | Required when source=reddit; rejected otherwise. Format r/<name>. r/all and r/new are rejected. |
page_token | query | string | null | no | Opaque cursor from a prior linked-content response’s pagination.next_page_token. Omit on the first request. |
max_page_size | query | integer, min: 1, default: 1 | no | Linked-content chunks per page. Increase when you want fewer round trips and can process more chunk text per call. |
Full REST reference — parameters, schemas, and curl →
REST reference
Section titled “REST reference”Prefer plain HTTP? The Social Monitoring API REST reference documents every operation with full request/response schemas and ready-to-run curl and agent-data CLI examples.