Post Search & Filter API - Retrieve Posts from Watchlists

Retrieve and filter LinkedIn or Reddit posts from your watchlists. Search, date range, seniority, trending, language, labels, relevance level, and more.

Retrieve posts collected by your watchlists. The endpoint serves both LinkedIn watchlists (keyword, people, company) and Reddit watchlists from the same URL: the source is auto-detected from the watchlist’s type, so you do not pass anything to switch between them. The shared response fields are identical for both sources, with a source field on each post and a few source-specific extras described in the Reddit watchlists section.

Query Parameters

watchlist_id · string · required

Watchlist ID to retrieve posts from. This parameter is required and must be a single watchlist ID.

page · number · default: "1"

Page number for pagination. Combine with page_size to control how many posts you get per page (defaults to 20).

page_size · number · default: "20"

Number of posts returned per page. Used together with page (or on its own) for offset-free pagination, e.g. page=2&page_size=50 returns posts 51 to 100.

Filtering Parameters

labels · string | array

Filter by label tags. Multiple labels can be specified.

people_slug · string | array

Filter by specific people (profile slugs). LinkedIn watchlists only; ignored on Reddit.

company_slug · string | array

Filter by specific companies (company slugs). LinkedIn watchlists only; ignored on Reddit.

search_term · string

Search within post content. LinkedIn watchlists only; ignored on Reddit.

is_saved · boolean

Filter for bookmarked/saved posts only. Works on both LinkedIn and Reddit.

lang · string | boolean

Restrict results to English posts only. Accepts "en", "english", "true", or true. Any other value is ignored.

Non-English language filtering is not currently supported, posts in other languages can be retrieved by omitting this parameter.

LinkedIn watchlists only; ignored on Reddit (Reddit posts do not carry a language field).

start_date · string

Filter posts from this date onwards (ISO 8601 format: YYYY-MM-DD). Works on both LinkedIn and Reddit.

end_date · string

Filter posts up to this date (ISO 8601 format: YYYY-MM-DD). Works on both LinkedIn and Reddit.

post_type · string

Filter by post type (e.g., “article”, “image”, “video”, “poll”). LinkedIn watchlists only; ignored on Reddit.

trending · boolean

Filter for trending posts with high engagement. LinkedIn watchlists only; ignored on Reddit.

interacted · boolean

Filter for posts you’ve already liked or commented on. LinkedIn watchlists only; ignored on Reddit.

seniority_level · string | array

Filter by author’s seniority level. Supports multiple comma-separated values (e.g., "VP,Director,CXO"). Common values: "Entry", "Manager", "Director", "VP", "CXO", "Founder". LinkedIn watchlists only; ignored on Reddit (Reddit does not have author profile data).

linkedin_post_slug · string

Retrieve a specific post by its LinkedIn slug. LinkedIn watchlists only; ignored on Reddit.

relevance_level · string | array

Reddit watchlists only. Filter by post relevance bucket. Supports multiple comma-separated values (e.g. "high,medium"). Allowed values: "high" (relevance score 8 to 10), "medium" (4 to 7), "low" (1 to 3). Ignored on LinkedIn watchlists.

Sorting Parameters

sort_by · string · default: "recent"

Sort order for posts. Options:

• recent: most recent posts first (default; both sources)
• popular_first: highest engagement (likes plus comments) first (LinkedIn). On Reddit, this aliases to relevance_first.
• engagement: alias for popular_first (LinkedIn). On Reddit, also aliases to relevance_first.
• relevance_first: Reddit watchlists only. Sorts by relevance score, highest first, then by post date.

range_from · number · default: "0"

Pagination start offset (0-indexed). Use with range_to for custom page sizes.

range_to · number · default: "19"

Pagination end offset (inclusive). Default returns 20 posts (0-19).

Get Posts from Specific Watchlist

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=550e8400-e29b-41d4-a716-446655440000&page=1" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "post-123",
      "linkedin_post_url": "https://linkedin.com/feed/update/urn:li:activity:1234567890",
      "tracking_list_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "Excited to announce our new AI-powered feature that helps developers...",
      "author_name": "Jane Smith",
      "author_url": "janesmith",
      "author_headline": "CTO at TechCorp | AI Enthusiast",
      "author_image_url": "https://media.licdn.com/dms/image/...",
      "created_at": "2024-01-15T10:35:00Z",
      "posted_at": "2024-01-15T10:30:00Z",
      "likes_count": 245,
      "comments_count": 32,
      "shares_count": 18,
      "bookmark": false,
      "post_type": "image",
      "language": "en",
      "tags": ["ai", "product-launch"],
      "image_urls": ["https://media.licdn.com/dms/image/..."],
      "videos": null,
      "seniority_level": "C-Level",
      "relevance_score": 8,
      "location_countries": ["United States"],
      "tagDescriptions": [
        {
          "tag": "ai",
          "description": "Artificial Intelligence related posts"
        }
      ]
    }
  ],
  "count": 156
}

Response Fields

data · array

Array of post objects

count · number

Total number of posts matching the filters

Post Object Fields

id · string

Unique post identifier

linkedin_post_url · string

Direct URL to the LinkedIn post. null on Reddit watchlists; see reddit_url instead.

tracking_list_id · string

ID of the watchlist this post belongs to

content · string

Post text content

author_name · string

Name of the post author

author_url · string

LinkedIn profile slug of the author

author_headline · string

Headline/bio of the post author

author_image_url · string

Profile image URL of the author

created_at · string

ISO 8601 timestamp when the post was added to OutX

posted_at · string

ISO 8601 timestamp when the post was published on LinkedIn

likes_count · number

Number of likes on the post

comments_count · number

Number of comments on the post

shares_count · number

Number of shares/reposts

bookmark · boolean

Whether the post has been bookmarked/saved

post_type · string

Type of post (e.g., “text”, “image”, “video”, “article”, “poll”)

language · string

Detected language of the post. Empty string on Reddit watchlists.

tags · array

Array of tag labels assigned to the post

image_urls · array

Array of image URLs attached to the post

videos · array

Array of video data attached to the post

seniority_level · string

Seniority level of the post author (e.g., “C-Level”, “VP”, “Director”). Empty string on Reddit watchlists.

relevance_score · number

Relevance score of the post (1-10). High: 8-10, Medium: 4-7, Low: 1-3. Returned for both LinkedIn and Reddit posts.

location_countries · array

Array of countries associated with the post author’s location. null on Reddit watchlists.

tagDescriptions · array

Array of objects with tag and description for each tag.

Reddit watchlists

The /api-posts endpoint also serves Reddit watchlists. The URL, authentication, and pagination are identical to the LinkedIn flow; pass the Reddit watchlist’s id as watchlist_id and the server detects the source from tracking_lists.type.

A Reddit row in data represents either a Reddit post or a top-level comment that matched one of the watchlist keywords. The shared response fields above are filled best-effort, with these source-specific differences:

• A discriminator field, source: "reddit", is present on every Reddit row. LinkedIn rows do not include this field.
• linkedin_post_url, videos, and location_countries are always null.
• language, author_url, author_headline, and seniority_level are empty strings (Reddit posts do not carry these data).
• shares_count and comments_count are always 0. Use comment_* and post_vote_count mappings instead.
• likes_count is the Reddit post upvote net score (mapped from post_vote_count).
• tags is a single-element array derived from the row’s label column.
• post_type is "reddit_post" for posts and "reddit_comment" for comments.

Reddit rows include these additional fields:

source · string

Always "reddit" on Reddit rows. Absent on LinkedIn rows.

reddit_url · string

Direct URL to the Reddit post or comment.

post_title · string

Reddit post title. May be null for rows that represent a comment under a post that was not separately ingested.

post_content · string

Body of the Reddit post.

subreddit · string

Subreddit name (e.g. r/dataengineering). Mapped from the underlying post_group_name column.

comment_author · string

Reddit username of the comment author. null when the row is a post.

comment_content · string

Comment body. null when the row is a post.

comment_created_at · string

ISO 8601 timestamp of the comment. null when the row is a post.

comment_vote_count · number

Reddit comment upvote net score. 0 when the row is a post.

relevance_level · string

Bucketed relevance: "high", "medium", or "low". Derived from relevance_score. null if the post has not been scored.

primary_keywords · array

Array containing the watchlist keyword that matched this row. Empty if the row is no longer linked to a keyword (for example after a watchlist update).

Reddit response example

Response (Reddit watchlist)

{
  "data": [
    {
      "id": "9f3c4f7a-12bc-4d5e-9a01-77b91f4b7c10",
      "source": "reddit",
      "tracking_list_id": "29aaf845-65bc-4cf8-9454-a398400bf067",
      "reddit_url": "https://www.reddit.com/r/dataengineering/comments/abc123/title/",
      "linkedin_post_url": null,
      "content": "Anyone else hitting this with the new connector? ...",
      "author_name": "u/example_user",
      "author_url": "",
      "author_headline": "",
      "author_image_url": null,
      "created_at": "2026-05-04T08:12:33Z",
      "posted_at": "2026-05-04T07:55:00Z",
      "likes_count": 47,
      "comments_count": 0,
      "shares_count": 0,
      "bookmark": false,
      "post_type": "reddit_post",
      "language": "",
      "tags": ["data-integration-pain"],
      "image_urls": null,
      "videos": null,
      "seniority_level": "",
      "relevance_score": 8,
      "relevance_level": "high",
      "location_countries": null,
      "tagDescriptions": [
        {
          "tag": "data-integration-pain",
          "description": "Posts where users describe specific integration failures"
        }
      ],
      "post_title": "Snowflake to BigQuery sync silently dropping rows",
      "post_content": "Anyone else hitting this with the new connector? ...",
      "subreddit": "r/dataengineering",
      "comment_author": null,
      "comment_content": null,
      "comment_created_at": null,
      "comment_vote_count": 0,
      "primary_keywords": ["data integration"]
    }
  ],
  "count": 73
}

Reddit examples

Get posts from a Reddit watchlist

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=29aaf845-65bc-4cf8-9454-a398400bf067" \
  -H "x-api-key: YOUR_API_KEY"

High-relevance Reddit posts only

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=29aaf845-65bc-4cf8-9454-a398400bf067&relevance_level=high&sort_by=relevance_first" \
  -H "x-api-key: YOUR_API_KEY"

Pagination

Posts are returned in batches of 20 by default. You can use either page + page_size (simpler) or range_from + range_to (offset-based) to paginate.

# First 20 posts from a watchlist (default)
GET /api-posts?watchlist_id=YOUR_ID

# 50 posts per page using page_size
GET /api-posts?watchlist_id=YOUR_ID&page=1&page_size=50

# Posts 21-40 using range_from / range_to
GET /api-posts?watchlist_id=YOUR_ID&range_from=20&range_to=39

The count field in the response shows the total number of posts matching your filters, so you know how many pages to fetch.

Error Responses

Status Code	Error Message	Description
400	Invalid watchlist ID	The provided watchlist ID doesn’t exist
401	Unauthorized	Invalid or missing API key
403	Access denied	Trying to access watchlists from another team
500	Failed to fetch posts	Internal server error

Frequently Asked Questions

Can I get posts from all my watchlists at once?

No. The api-posts endpoint now requires a single watchlist_id and returns posts for that watchlist only. To build a unified feed across multiple watchlists, make separate requests per watchlist and merge the results on your side.

What is the maximum number of posts returned per page?

The default page size is 20 posts. To change it, pass page_size (for example page_size=50 returns 50 posts per page), or use range_from and range_to for offset-based pagination (e.g. range_from=0&range_to=49 returns the first 50). The count field in the response tells you the total number of matching posts so you know how many pages to fetch.

How do I filter by multiple seniority levels?

Pass comma-separated values to the seniority_level parameter. For example: seniority_level=VP,Director,CXO. This returns posts authored by people at any of those seniority levels. Common values include Entry, Manager, Director, VP, CXO, and Founder.