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

# POST /v1/find_intent

`POST /v1/find_intent`

## Request

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

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `audience` string: Optional goal: what you sell and to whom. Always accepted. Until goal ordering is available, signals keep today’s order with ranking.by recency and date-based why_now flags; no change to charges.
  - `company_domains` string[], required
  - `since` string, date
  - `within_days` integer
  - `roles` string[]: Hiring role filter, up to 25 job titles or phrases: a hiring post counts only when it is one of these roles. Put a role in double quotes to match it word for word. Applies to hiring only; job_change events carry no structured role field.
  - `signals` string[]: Signal families to check. hiring = live job posts with evidence URLs; funding, news, job_change = dated events. Omit it to check hiring first: only hiring is checked, and a hiring company's latest funding round comes with it; list funding explicitly to check every company (a paid check). DEPRECATED: technology — a present-day vendor detection with no adoption date, not a buying signal; use find_companies.technologies instead. Still accepted in v1.
  - `budget_credits` number: Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged. No company you sent is dropped to fit. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason.
  - `dry_run` boolean: Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason.

## Response `200`

Successful outcome

- object
  - `result` union, required
    - object
      - `next` object[]
        - `reason` 'check_funding' | 'check_news' | 'research_strongest' | 'research_deeper' | 'find_people' | 'find_profile', required
        - `text` string, required
        - `verb` 'find_intent' | 'research_company' | 'find_leads' | 'enrich', required
        - `params` object, required
        - `max_credits` string, required
      - `ranking` object
        - `by` 'goal' | 'recency', required
        - `judged` integer, required
        - `unsure` integer
        - `version` string, required
        - `why_now_judged` integer
        - `companies` string[]
      - `signals` object[], required
        - `company_domain` string, required
        - `signal` 'hiring' | 'technology' | 'funding' | 'news' | 'job_change', required
        - `summary` string, required
        - `observed_at` string, required
        - `evidence_url` string, nullable, required
        - `title` string
        - `news_type` 'funding' | 'product' | 'partnership' | 'customers' | 'expansion' | 'leadership' | 'layoffs' | 'acquisition' | 'challenges' | 'recognition' | 'other'
        - `why_now` boolean
        - `why_now_basis` 'judged' | 'date'
      - `domain_status` object[]
        - `company_domain` string, required
        - `status` 'complete' | 'partial' | 'unavailable', required
        - `requested_signals` string[], required
        - `completed_signals` string[], required
        - `unavailable_signals` object[], required
          - `signal` 'hiring' | 'technology' | 'funding' | 'news' | 'job_change', required
          - `reason` 'vendor_account' | 'invalid_request' | 'rate_limited' | 'temporarily_paused' | 'upstream_error', required
          - `retry_after_seconds` integer
        - `skipped_signals` object[]
          - `signal` 'hiring' | 'technology' | 'funding' | 'news' | 'job_change', required
          - `reason` 'default_hiring_first', required
        - `charge` object
          - `credits` string, required
          - `signal` boolean, required
          - `paid_checks` integer, required
        - `roles_check` object
          - `method` 'meaning' | 'literal', required
          - `postings_rejected` integer, required
      - `historical` object[]
        - `company_domain` string, required
        - `signal` 'hiring' | 'technology' | 'funding' | 'news' | 'job_change', required
        - `summary` string, required
        - `observed_at` string, required
        - `evidence_url` string, nullable, required
        - `title` string
        - `news_type` 'funding' | 'product' | 'partnership' | 'customers' | 'expansion' | 'leadership' | 'layoffs' | 'acquisition' | 'challenges' | 'recognition' | 'other'
        - `why_now` boolean
        - `why_now_basis` 'judged' | 'date'
      - `window` object
        - `from` string, required
        - `to` string, required
        - `within_days` integer
      - `interpreted` object
        - `roles_searched` string[], required
        - `version` string, required
    - object
      - `dry_run` true, required
      - `advisory` true, required
      - `evaluated_at` string, required
      - `plan` object, required
        - `verb` 'find_intent', required
        - `plan_version` 3, required
        - `input_version` string, required
        - `credits_estimate` string, required
        - `would_exceed` string[], required
        - `warnings` string[], required
        - `would` object, required
          - `companies` integer, required
          - `candidate_sources` integer, required
          - `maximum_credits` string, required
          - `budget_credits` string, nullable, 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)