---
title: "POST /v1/find_posts"
method: POST
path: "/v1/find_posts"
tags: ["GTM verbs"]
---

# POST /v1/find_posts

`POST /v1/find_posts`

## Request

- Base URL: `https://api.layrcake.dev`
- URL: `https://api.layrcake.dev/v1/find_posts`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string
  - `author` union
    - object
      - `type` 'profile_url', required
      - `profile_url` string, uri, required
    - object
      - `type` 'handle', required
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
      - `handle` string, required
    - object
      - `type` 'person', required
      - `name` string, required
      - `company_domain` string: Company website domain or URL, e.g. acme.com or https://www.acme.com/about
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
  - `company_domain` string: Company website domain or URL, e.g. acme.com or https://www.acme.com/about
  - `intent` 'pain' | 'question' | 'any' | 'competitor_complaint' | 'hiring_for_it'
  - `audience` string
  - `platforms` string[]
  - `within_days` integer
  - `limit` integer
  - `include` string[]
  - `leads` object[]: 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.
    - `fingerprint` string, nullable
    - `full_name` string, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `title` string, nullable
    - `company_name` string, nullable
    - `company_domain` string, nullable
    - `linkedin_url` string, nullable
    - `email` string, nullable
    - `work_email` string, nullable
  - `budget_credits` number: 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.
  - `engagers_of` string[]: 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.
  - `per_post` integer: Engagers mode: up to this many people from each source (reactions, comments, replies) of each post.
  - `author_filter` string[]: 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).
  - `read_all` true: 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.

## Response `200`

Successful outcome

- object
  - `result` object, required
    - `outcome` 'hit' | 'partial' | 'miss', required
    - `posts` object[], required
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
      - `post_id` string, required
      - `url` string, uri, required
      - `text` string, required
      - `author` object, required
        - `name` string, nullable, required
        - `handle` string, nullable, required
        - `social_profile_url` string, uri, nullable, required
        - `headline` string, nullable, required
        - `verified` boolean, nullable, required
        - `followers` integer, nullable, required
        - `person` object, required
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `email` string
          - `linkedin_url` string, uri
          - `company_name` string
          - `company_domain` string
          - `title` string
        - `type` 'person' | 'company'
      - `published_at` union, required
        - string, date
        - string, date-time
      - `engagement` object, required
        - `likes` integer, nullable, required
        - `comments` integer, nullable, required
        - `shares` integer, nullable, required
        - `views` integer, nullable, required
      - `relevance` number, required
      - `classification` object
        - `label` 'pain' | 'question' | 'pitch' | 'opinion' | 'other', required
        - `reason` string, required
        - `prompt_version` string, required
        - `status` 'classified', required
        - `tags` string[]
      - `is_repost` boolean
      - `why_now` boolean
      - `why_now_basis` 'judged' | 'date'
    - `platform_status` object[], required
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
      - `status` 'hit' | 'miss' | 'unavailable' | 'timeout' | 'unsupported', required
      - `returned` integer, required
      - `more_available` boolean, nullable, required
      - `classification_status` 'classified' | 'unavailable' | 'not_requested'
    - `author_resolutions` object[]
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
      - `status` 'resolved' | 'ambiguous' | 'unresolved' | 'unsupported', required
      - `handle` string
      - `profile_url` string, uri
      - `confidence` number
      - `candidates` object[]
        - `name` string, nullable, required
        - `handle` string, nullable, required
        - `profile_url` string, uri, nullable, required
        - `confidence` number, required
    - `relevance_version` 'literal-v1', required
    - `more_available` boolean, nullable, required
    - `leads` object[]
      - `lead` object, required
        - `key` string, required
        - `full_name` string, nullable, required
        - `company_name` string, nullable, required
      - `status` 'signal' | 'none' | 'incomplete' | 'not_processed', required
      - `signal_kind` 'own_post' | 'comment' | 'reaction' | 'company_post', nullable, required
      - `evidence` object, nullable, required
        - `text` string, required
        - `url` string, uri, required
        - `date` union, required
          - string, date
          - string, date-time
        - `activity` 'reaction' | 'comment', nullable, required
        - `reaction` string, nullable, required
        - `post_author` string, nullable, required
      - `post_ids` string[], required
      - `person` object, required
        - `full_name` string
        - `first_name` string
        - `last_name` string
        - `email` string
        - `linkedin_url` string, uri
        - `company_name` string
        - `company_domain` string
        - `title` string
    - `engagers` object[]
      - `post_url` string, uri, required
      - `platform` 'linkedin' | 'x' | 'reddit' | 'youtube' | 'tiktok' | 'instagram' | 'facebook' | 'threads' | 'hackernews' | 'quora', required
      - `status` 'hit' | 'miss' | 'incomplete' | 'not_searched', required
      - `people` object[], required
        - `name` string, nullable, required
        - `profile_url` string, uri, required
        - `handle` string, nullable, required
        - `headline` string, nullable, required
        - `type` 'person' | 'company', required
        - `activities` object[], required
          - `kind` 'reaction' | 'comment' | 'reply' | 'repost', required
          - `reaction` string, nullable, required
          - `text` string, nullable, required
          - `at` union, required
            - string, date
            - string, date-time
        - `person` object, required
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `email` string
          - `linkedin_url` string, uri
          - `company_name` string
          - `company_domain` string
          - `title` string
        - `matched_by` 'literal' | 'judged'
      - `filtered_out` integer, required
      - `scanned` integer
      - `read` integer
      - `engaged_total` integer, nullable
      - `more_available` boolean, nullable
    - `filter_basis` 'literal' | 'judged'
    - `full_read` object
      - `budget_credits` number, required
      - `eta_seconds` integer, required
    - `ranking` object
      - `by` 'goal' | 'recency', required
      - `judged` integer, required
      - `unsure` integer
      - `version` string, required
      - `why_now_judged` integer
      - `companies` string[]
    - `intent` 'pain' | 'question' | 'any' | 'competitor_complaint' | 'hiring_for_it'
    - `cost_breakdown` object
      - `result_credits` string, required
      - `classification_credits` string, required
      - `candidates_classified` integer, required
      - `candidates_withheld` integer, required
      - `classification_versions` object
        - `classifier` string, required
        - `prompt` string, required
  - `layrcake` object, required
    - `request_id` string, uuid, required
    - `credits_charged` string, required
    - `credits_available` string, required
    - `replayed` boolean
    - `route` object
      - `used` 'balanced' | 'cheapest' | 'broadest' | 'fastest', required
      - `source` 'request' | 'key' | 'guess' | 'default', required

## Other responses

- `4XX`: Caller, scope, confirmation, or credit error
- `5XX`: Provider or service error

---

[API](https://skmtc.dev/layrcake/apis/layrcake-api.md) · [All operations](https://skmtc.dev/layrcake/apis/layrcake-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layrcake/apis/layrcake-api/revisions/24c80e33c274?raw)