pull posts

One page of what a platform is publishing, stored nowhere: each post’s words (the first 600 characters, text_chars the whole length), dates, handle or advertiser, engagement, views_per_day on organic posts (views at the rate since posting, scaled to a day; absent where posted_at_precision marks the date as right to that unit only), permalink, and a count of its media; media: true adds each address at the source, which expires within days, for inspect_media urls. keep_posts keeps chosen posts with their whole text, by id, for two days after the pull. source plus an account or a query; next_cursor is the page after, and the same ask 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, a fraction of one, whatever the thresholds drop, an empty page included; an error answer from the source and a transcript with no words are not charged; a timeout is.

POST

tools

pull_posts

pull posts

curl --request POST \
  --url https://eversince.ai/api/v1/tools/pull_posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "<string>",
  "query": "<string>",
  "cursor": "<string>",
  "comments_of": "<string>",
  "transcript_of": "<string>",
  "market": "<string>",
  "since": "<string>",
  "until": "<string>",
  "order": "<string>",
  "posted": "<string>",
  "language": "<string>",
  "duration": "<string>",
  "media": true,
  "min_views": 123,
  "min_likes": 123,
  "min_comments": 123,
  "min_shares": 123,
  "within_days": 123,
  "context": "<string>"
}
'

import requests

url = "https://eversince.ai/api/v1/tools/pull_posts"

payload = {
    "account": "<string>",
    "query": "<string>",
    "cursor": "<string>",
    "comments_of": "<string>",
    "transcript_of": "<string>",
    "market": "<string>",
    "since": "<string>",
    "until": "<string>",
    "order": "<string>",
    "posted": "<string>",
    "language": "<string>",
    "duration": "<string>",
    "media": True,
    "min_views": 123,
    "min_likes": 123,
    "min_comments": 123,
    "min_shares": 123,
    "within_days": 123,
    "context": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '<string>',
    query: '<string>',
    cursor: '<string>',
    comments_of: '<string>',
    transcript_of: '<string>',
    market: '<string>',
    since: '<string>',
    until: '<string>',
    order: '<string>',
    posted: '<string>',
    language: '<string>',
    duration: '<string>',
    media: true,
    min_views: 123,
    min_likes: 123,
    min_comments: 123,
    min_shares: 123,
    within_days: 123,
    context: '<string>'
  })
};

fetch('https://eversince.ai/api/v1/tools/pull_posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "ok": true,
  "data": {},
  "meta": {
    "request_id": "<string>",
    "cost": {},
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  },
  "media": [
    {}
  ]
}

{
  "ok": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  }
}

Authorizations

Authorization

string

header

required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key

string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id

string

The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.

Body

application/json

source

enum<string>

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 only: 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). Elsewhere no language is given; it is read from the post's own text.

Available options:

meta_ads,

tiktok_ads,

linkedin_ads,

tiktok,

instagram,

youtube,

reddit,

linkedin,

x,

threads,

pinterest,

google_ads,

tiktok_shop

account

string

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 (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 website domain (example.com) or an AR advertiser id; reddit: r/name or a subreddit link pulls that subreddit, other words are keywords. linkedin, x, threads, pinterest and tiktok_shop take query only. This or query.

query

string

Keywords, for a niche rather than a named account. On instagram, one #hashtag reads that hashtag's public posts and reels.

cursor

string

The next_cursor a previous pull returned, for the page after it; with comments_of, the next page of comments. Each page is its own call and its own charge. instagram by query, linkedin and x page up to page 11; threads has one page.

comments_of

string

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 never kept.

transcript_of

string

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; never kept. Other platforms: keep_posts, then transcribe_media.

market

string

2-letter market, e.g. "US". meta_ads, linkedin_ads, google_ads and tiktok_shop (US is reliable; others may come back thin) only; the other sources have no market parameter.

status

enum<string>

meta_ads only, active by default. "inactive" is what a brand has stopped running.

Available options:

active,

inactive,

all

since

string

YYYY-MM-DD. meta_ads (the impressions window), linkedin_ads (the run window), google_ads (when shown) and threads (when posted) only.

until

string

YYYY-MM-DD. As since.

order

string

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.

posted

string

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 the reel was found, so within_days narrows it by the post's own 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.

match

enum<string>

meta_ads with a query: exact_phrase for a multi-word product or brand name that must match whole.

Available options:

keyword_unordered,

keyword_exact_phrase

language

string

2-letter ad language, e.g. "EN". meta_ads by account only.

duration

string

youtube by query only: under_3_min, between_3_and_20_min, over_20_min.

content_type

enum<string>

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.

Available options:

videos,

shorts,

all

media

boolean

true: each post's media addresses, for inspect_media urls. Omitted: a count.

min_views

number

Keeps only posts with at least this many views. Applied to the page after it is fetched: the page is still one charge, below_threshold counts what was dropped, page_spread its top and median. A post without the number is dropped.

min_likes

number

As min_views, for likes (score on reddit).

min_comments

number

As min_views, for comments.

min_shares

number

As min_views, for shares (reposts on x and threads).

within_days

number

Keeps only posts posted within this many days, by posted_at, applied like min_views.

context

string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

any

required

data

object

required

meta

object

required

Show child attributes

media

object[]

pull posts

curl --request POST \
  --url https://eversince.ai/api/v1/tools/pull_posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "<string>",
  "query": "<string>",
  "cursor": "<string>",
  "comments_of": "<string>",
  "transcript_of": "<string>",
  "market": "<string>",
  "since": "<string>",
  "until": "<string>",
  "order": "<string>",
  "posted": "<string>",
  "language": "<string>",
  "duration": "<string>",
  "media": true,
  "min_views": 123,
  "min_likes": 123,
  "min_comments": 123,
  "min_shares": 123,
  "within_days": 123,
  "context": "<string>"
}
'

import requests

url = "https://eversince.ai/api/v1/tools/pull_posts"

payload = {
    "account": "<string>",
    "query": "<string>",
    "cursor": "<string>",
    "comments_of": "<string>",
    "transcript_of": "<string>",
    "market": "<string>",
    "since": "<string>",
    "until": "<string>",
    "order": "<string>",
    "posted": "<string>",
    "language": "<string>",
    "duration": "<string>",
    "media": True,
    "min_views": 123,
    "min_likes": 123,
    "min_comments": 123,
    "min_shares": 123,
    "within_days": 123,
    "context": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '<string>',
    query: '<string>',
    cursor: '<string>',
    comments_of: '<string>',
    transcript_of: '<string>',
    market: '<string>',
    since: '<string>',
    until: '<string>',
    order: '<string>',
    posted: '<string>',
    language: '<string>',
    duration: '<string>',
    media: true,
    min_views: 123,
    min_likes: 123,
    min_comments: 123,
    min_shares: 123,
    within_days: 123,
    context: '<string>'
  })
};

fetch('https://eversince.ai/api/v1/tools/pull_posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "ok": true,
  "data": {},
  "meta": {
    "request_id": "<string>",
    "cost": {},
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  },
  "media": [
    {}
  ]
}

{
  "ok": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  }
}

Discovery

Timeline

Workspace

Library

Canvas

Generation

Research

Account

Models

Uploads

Webhooks

pull posts

Authorizations

Headers

Body

Response