Core concepts

Filtering posts

GET /posts and GET /collections/{collectionId}/posts accept the same set of filters. Add as many as you need — they combine with AND, so a post must match every filter to be returned. The same filters define a content selection for POST /analyses (selection.posts).

FilterWhat it doesExample
linkOnly the post at this URLlink=https://www.instagram.com/reel/ABC123/
accountOnly posts from this creatoraccount=@nike
tagOnly posts carrying this content tagtag=launch
platformOnly posts from these platformsplatform=instagram,tiktok
posted_since / posted_untilPosts published in a date rangeposted_since=2026-01-01&posted_until=2026-03-31
updated_sincePosts whose Siftsy data changed since a dateupdated_since=2026-03-01T00:00:00Z
min_score / max_scoreSiftsy score range (0–10)min_score=7
min_positive_percent / max_positive_percentShare of positive comments (0–100)min_positive_percent=60
min_negative_percent / max_negative_percentShare of negative comments (0–100)max_negative_percent=10
min_neutral_percent / max_neutral_percentShare of neutral commentsmax_neutral_percent=30
min_lean_positive_percent / max_lean_positive_percentShare of lean-positive comments
min_lean_negative_percent / max_lean_negative_percentShare of lean-negative comments
statusWhich processing states to include (default complete)status=all
collectionIdRestrict to one collection (GET /posts only). collection_id is an aliascollectionId=abc123

Examples

Posts with a Siftsy score of 7 or higher:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?min_score=7"

Everything from one creator on TikTok this quarter:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?account=@nike&platform=tiktok&posted_since=2026-07-01&posted_until=2026-09-30"

Posts where at least 60% of comments are positive and no more than 10% are negative:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?min_positive_percent=60&max_negative_percent=10"

Look up a single post by its URL:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?link=https://www.instagram.com/reel/ABC123/"

Low-scoring posts inside one collection:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/collections/YOUR_COLLECTION_ID/posts?max_score=4"

Posts tagged launch or preorder:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?tag=launch,preorder"

The same selection as an analysis body:

{ "selection": { "posts": { "tag": "launch,preorder" } } }

How matching works

  • Links are matched loosely: http vs https, www., trailing slashes, upper/lower case, and anything after ? or # are ignored. Tracking parameters like ?igsh= or ?utm_source= never break a match.
  • Accounts match the creator’s username or display name, case-insensitive. The leading @ is optional.
  • Tags are the content tags on the post in Siftsy, matched case-insensitively. The leading # is optional. Several tags match posts carrying any of them.
  • Lists: link, account, tag, and platform accept several values — comma-separate them (platform=instagram,tiktok) or repeat the parameter.
  • Dates are ISO 8601. A date without a time (2026-01-01) means midnight UTC.
  • Scores and percentages compare against the values in the post payload (scores.siftsyScore and sentimentMix.*), so what you filter on is exactly what you get back. Posts that have not finished scoring are excluded from score and sentiment filters.

The response echoes your active filters in meta.filters, so you can confirm exactly what was applied.

Filters and paging

Filters are applied while each page is being filled, so pages stay close to your limit rather than coming back nearly empty. To get the next page, send the same filters again and add the cursor from the previous response. Keep going until hasMore is false.

Invalid values (a bad date, min_score=11, min_score greater than max_score) return 400 with a message explaining what to fix.

To sample the comments behind a mix-bar bucket (evidence, not a full export), see Retrieving comments.