pull posts
One page of a platform’s public posts or ads, not saved to the workspace. Each post has its words (the first 600 characters, text_chars the whole length), dates, handle or advertiser, engagement, views_per_day on organic posts (average daily views since posting; absent when posted_at_precision is coarser than an hour), permalink, and a count of its media; media: true adds each media URL for inspect_media urls, expiring within days. keep_posts saves chosen posts by id, with full text, up to two days after the pull. Give source plus account or query; next_cursor is the page after, and the same request within 10 minutes returns the same page, uncharged. comments_of instead returns a page of one post’s comments; transcript_of, a YouTube or TikTok post’s spoken words. Organic sources have no country filter. A post already kept carries its ref. Credits: each page, comments page or transcript is one charge of a fraction of a credit, whatever the filters drop, an empty page included; an error from the source and a transcript with no words are not charged; a timeout is.
Authorizations
Headers
Body
Where to pull from; required unless comments_of or transcript_of is given. Ad libraries: meta_ads, tiktok_ads and linkedin_ads (creative and copy); google_ads (a company's ads: format, first and last shown, the ad's library link, a picture where Google renders one; no copy). tiktok gives shares, saves, language, creator_country, followers, hashtags, sound and paid; instagram by query gives duration, sound, paid, followers and top_comments; youtube gives likes, comments and the description, and a handle except on shorts by query, which carry no channel; reddit gives score and comments. Search by query: linkedin (Google-indexed posts: likes, comments, author followers), x (Google-indexed, ranked by Google: views, likes, replies, reposts as shares, quotes, bookmarks, followers), threads (one page of up to 20: likes, replies, reposts, quotes), pinterest (pins with no engagement counts: the pinner's followers, link and board), tiktok_shop (products: price, list_price, rating, reviews, sold, shop). Other sources return no language field; the post's text shows it.
meta_ads, tiktok_ads, linkedin_ads, tiktok, instagram, youtube, reddit, linkedin, x, threads, pinterest, facebook, google_ads, tiktok_shop A profile link, an @handle, or a name. tiktok, instagram and youtube: a link or handle pulls that account; a post's link pulls that post except on youtube and reddit; a name is searched on tiktok (two requests, priced as one; its next_cursor keeps that account), refused on instagram, read as keywords on youtube. meta_ads: an Ad Library link or a name it resolves; tiktok_ads and linkedin_ads: an advertiser name; google_ads: the domain (example.com) or an AR advertiser id; reddit: r/name or a subreddit link pulls that subreddit, other words are keywords. tiktok_shop takes query only; facebook, a post's link only. This or query.
A post's permalink, as a page returned it, on tiktok, instagram, youtube or reddit. Returns a page of that post's comments instead of posts: text, likes, replies, date, handle, and language on tiktok, with next_cursor. Instagram serves only the comments it shows the public, at times far fewer than the post's count, and no likes on them. source may be omitted. Priced as a page; comments are not kept.
A YouTube or TikTok post's permalink. Returns its spoken words from the platform's own captions as lines "m:ss words", with language on youtube; none, with a note and no charge, where the platform has no captions; about an hour at most, cut_at naming where it stopped. Priced as a page; not kept. Other platforms: keep_posts, then transcribe_media.
The source's own ordering. meta_ads: total_impressions (default) or relevancy_monthly_grouped. tiktok and youtube by account: latest, popular. tiktok by query: relevance, most-liked, date-posted. reddit by keywords: relevance, new, top, comment_count; a subreddit: best, hot, new, top, rising. youtube by query: relevance, popular. Others have none; an unknown value is dropped.
How far back, in the source's terms. tiktok by query: yesterday, this-week, this-month, last-3-months, last-6-months, all-time. instagram by query: last-week, last-month, last-year, by when Google indexed the reel, so within_days filters by post date; an instagram #hashtag and linkedin: last-hour, last-day, last-week, last-month, last-year. youtube by query: today, this_week, this_month, this_year, any. reddit: day, week, month, year, all. meta_ads, linkedin_ads, google_ads and threads use since and until.
youtube: shorts isolates short-form (by query, by relevance only, with no order or duration, and posted applies; by account, the channel's shorts); omit for both. tiktok by query: all adds photo carousels (TikTok's Top results); omit for videos.
videos, shorts, all As min_views, for shares (reposts on x and threads).

