Find social posts
find_postsFind public social posts by keyword (people discussing a topic), by a known author's profile URL or handle, or by LinkedIn company domain. For angles, what's changed, how to approach, or why now on one company or person, use research_company (a company) or prospect_picture (a person, their company, or both) instead. intent: pain | question keeps only posts one audience-specific model pass classified as buyer pain or a buying question (each returned post carries its label and reason; unclassifiable candidates are withheld, never returned unlabelled) and adds a separate classification component at llm token pricing, shown in result.cost_breakdown. Supports LinkedIn, X, Reddit and Facebook, and YouTube and TikTok by keyword, when enabled. include: ["author_details"] adds each author's type (person or company page) and whether the post is a repost. A keyword query is matched word for word (literal-v1): a post is kept only when it contains every quoted phrase and at least 70% of the other words exactly as written, rounded up, so 2 or 3 words must all appear. Send 2–3 core words the posts would use, not a sentence, and let intent do the judging. Returns per-platform status, with how many posts came back and how many the word match dropped, and bills only kept posts. Keyword search costs 0.5 credit per returned post and a miss is free; author/company scope adds a 1-credit base even when no post is returned. On Reddit and Facebook a returned post costs 2 credits. For a person known only by name, call enrich with person { full_name, company_domain } first, then pass the linkedin_url it returns as author { type: "profile_url", profile_url }; a name-only author is refused before any charge, with that call in error.details.next. intent also takes hiring_for_it (the author's own company hiring for the work your product does) and competitor_complaint (a user complaining about a tool like yours; it finds most, not all, complaint posts, so an empty answer doesn't mean nobody is complaining). audience is an optional goal: what you sell and to whom. It never changes charges. With a goal, posts are ordered by how worth a reply they are (ranking.by goal; recency when nothing was judged) and each carries why_now with why_now_basis judged or date. leads takes contacts as find_leads or enrich return them and gives each one's best recent reason to reach out (their own post, a comment, a reaction or their company's post) with the evidence, and the person ready for enrich: 3 credits per lead with a signal, a lead with none is free, budget_credits caps it. Up to 10 leads answer inline; up to 1,000 run as an operation: send idempotency_key, then poll get_operation, which returns the leads 25 at a time with next_cursor. engagers_of takes up to 5 post URLs and returns the people who reacted, commented, replied or reposted, each with what they did and ready for enrich: 0.5 credit per person (2 on Reddit), a post with nobody is free, per_post up to 50. author_filter (headline or bio keywords) keeps only matching people, adds 0.4 credit per person read, and skips Reddit and Facebook, whose people show no headline. Choose posts your buyers engage with. A company's own announcements can draw mostly its own staff, so check who engaged, or pass author_filter with title words (for example head of sales, VP sales) to keep only the roles you want. Each post reports read (people read) and, on LinkedIn, engaged_total; more_available true means the sample missed people. To read everyone, send the same posts with read_all: true, budget_credits and idempotency_key: it runs in the background (about 2 minutes per 500 people) at the same price per person kept, plus 0.4 credit per person read with author_filter, and never charges above budget_credits. When the counts are known the sample's full_read quotes that budget and the time: tell the user before running it. Then poll get_operation, which returns the people 25 at a time with next_cursor. If the budget runs short, each post says how many people were not read (not_read) or withheld (withheld) and limited_by budget: raise budget_credits to get them. With author_filter, a title check also keeps people whose headline clearly means one of your terms in other words (a CCO for chief revenue officer): each is marked matched_by judged, and filter_basis says judged when it added anyone. It only adds people, and a full read checks at most 2,500 of them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| leads | No | Leads mode: people from find_leads or enrich. Returns each one's best recent reason to reach out (own post, comment, reaction or company post). LinkedIn only: send no query, platforms or intent. | |
| limit | No | ||
| query | No | ||
| author | No | ||
| intent | No | ||
| include | No | ||
| audience | No | ||
| per_post | No | Engagers mode: up to this many people from each source (reactions, comments, replies) of each post. | |
| read_all | No | Engagers mode: read everyone who engaged, not a sample, in the background (about 2 minutes per 500 people). Needs budget_credits and idempotency_key. Returns an operation: poll get_operation, which returns the people 25 at a time with next_cursor. | |
| platforms | No | ||
| engagers_of | No | Engagers mode: up to 5 post URLs (LinkedIn, X, Reddit, Facebook). Returns the people who reacted, commented, replied or reposted. Send no query, platforms, intent or audience. | |
| within_days | No | ||
| author_filter | No | Engagers mode: keep only people whose headline contains one of these words, e.g. ["head of sales", "VP sales"]. Each person read costs a small scan fee; Reddit and Facebook are skipped (no headlines). | |
| budget_credits | No | Leads mode, or engagers_of with read_all: a spend ceiling in credits. Leads beyond it come back not_processed; read_all reads people up to it. | |
| company_domain | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |