pull posts
One page of what a platform is publishing, stored nowhere: each post’s words, dates, handle or advertiser, engagement, permalink, and every picture and video at the source’s address, which expires within days. inspect_media urls looks at them, and with a prompt has a model answer about one; transcribe_media takes them too. keep_posts keeps chosen posts within two days. source plus an account or a query; next_cursor is the page after, and the same ask again returns the same page. A post already kept carries its ref. The answer names the account it reached. Credits, a fraction of one a page.
Authorizations
An API key (es_live_…) from Settings, under API keys, or an OAuth access token.
Headers
Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.
The workspace this one call acts in, when it is not the key's own.
Body
Where to pull from. meta_ads, tiktok_ads and linkedin_ads are ad libraries and carry ad creative and copy; tiktok, instagram, youtube and reddit are organic.
meta_ads, tiktok_ads, linkedin_ads, tiktok, instagram, youtube, reddit A profile link, an @handle, or a name. tiktok, instagram and youtube: a link or handle pulls that account; a name is searched on tiktok, refused on instagram, read as keywords on youtube. meta_ads: an Ad Library link or a name it resolves; tiktok_ads and linkedin_ads: a name; reddit: keywords. This or query.
Keywords, for a niche rather than a named account.
The next_cursor a previous pull returned, for the page after it. Each page is its own call and its own charge. Absent from the sources that page nothing: instagram by query, youtube by query.
2-letter market, e.g. "US". meta_ads, tiktok_ads and linkedin_ads only; the organic sources have no market parameter and answer globally.
meta_ads only, active by default. "inactive" is what a brand has stopped running.
active, inactive, all YYYY-MM-DD. meta_ads (the impressions window) and linkedin_ads (the run window) only.
YYYY-MM-DD. meta_ads and linkedin_ads only.
The source's own ordering. meta_ads: total_impressions (default) or relevancy_monthly_grouped. tiktok_ads: for_you, impression, play_2s_rate, play_6s_rate, cvr, ctr, like. tiktok and youtube by account: latest, popular. tiktok by query: relevance, most-liked, date-posted. reddit: relevance, new, top, comment_count. 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-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. Ad libraries use since and until.
meta_ads with a query: exact_phrase for a multi-word product or brand name that must match whole.
keyword_unordered, keyword_exact_phrase 2-letter ad language, e.g. "EN". meta_ads by account and tiktok_ads only, and it narrows a market pull to one language.
tiktok_ads only: a Creative Center category, named however you like; it is resolved to the platform's own taxonomy key, and dropped when nothing matches.
tiktok_ads only: the campaign objective.
app_installs, conversions, lead_generation, product_sales, reach, traffic, video_views How long the piece runs, in the source's buckets. tiktok_ads: under_10s, 10_20s, 20_30s, 30_40s, 40_50s, over_50s. youtube by query: under_3_min, between_3_and_20_min, over_20_min.
tiktok_ads only: the likes percentile band, top_1_20 being the best-performing.
top_1_20, top_21_40, top_41_60, top_61_80, top_81_100 tiktok_ads only.
spark_ads, non_spark_ads tiktok_ads only: the top-ads window in days.
youtube by query only: shorts isolates short-form. Omit for both.
videos, shorts Optional: one sentence shown to the user beside this action.
600