> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# collect signals

`POST /signals/collect`

Collects one LinkedIn profile, post or company page once. Company followers have a minimum order of 100, accept max_followers, reserve exactly the requested count and always answer 202. Without max_followers, a company job asks for at most the premium credits available and adds a max_followers_missing warning. One credit per unique lead settles when results arrive. A page below the minimum answers `signals.below_minimum` (HTTP 400) with the follower count in error.details. With dry_run true, returns a free estimate without admission. Engagement collects support wait for estimates at most 500. The 202 answer carries job.id. Poll get_collect (GET /signals/collect/{id}) every 30 to 60 seconds until status is completed or failed. Then read the rows with list_signals (GET /signals): source_type collect and source_id the job id.

Collects one LinkedIn profile, post or company page once. Company followers have a minimum order of 100, accept max_followers, reserve exactly the requested count and always answer 202. Without max_followers, a company job asks for at most the premium credits available and adds a max_followers_missing warning. One credit per unique lead settles when results arrive. A page below the minimum answers `signals.below_minimum` (HTTP 400) with the follower count in error.details. With dry_run true, returns a free estimate without admission. Engagement collects support wait for estimates at most 500. The 202 answer carries job.id. Poll get_collect (GET /signals/collect/{id}) every 30 to 60 seconds until status is completed or failed. Then read the rows with list_signals (GET /signals): source_type collect and source_id the job id.

Cost: One premium credit per lead; holds twice the expected engagers, or exactly the requested company followers (without max_followers, at most the premium credits available). Premium credits are held before work starts, and a dry run is free.

## Request body

- `kind` | enum | required. What to collect. linkedin_profile: the people who react to or comment on the 10 latest posts of one profile. linkedin_post: the people who react to or comment on one post. linkedin_company: the followers of one company page. Values: `linkedin_profile`, `linkedin_post`, `linkedin_company`.
- `target` | string | required. The LinkedIn URL of the target. A profile URL, such as https://www.linkedin.com/in/<slug>. A post URL of the form https://www.linkedin.com/posts/<slug> or https://www.linkedin.com/feed/update/urn:li:activity:<id>. A company URL, such as https://www.linkedin.com/company/<slug>.
- `max_followers` | integer | optional. For linkedin_company only: the most followers to collect, at least 100 and at most one million. Without it, a company job asks for at most the premium credits available, with a minimum of 100, and adds a max_followers_missing warning.
- `wait` | boolean | optional. True keeps the request open until the rows are ready, for at most about 45 seconds, when the estimate is 500 engagers or fewer. A company page never waits. Otherwise the job runs in the background; read its rows with list_signals.
- `dry_run` | boolean | optional. True returns only the estimate: units, premium_credits, available and sufficient. It holds no credits, starts no job and costs nothing.

## Response

- `job` | object | required.
  - `kind` | enum | required.  Values: `linkedin_profile`, `linkedin_post`, `linkedin_company`.
  - `target` | string | required.
  - `id` | string | required.
  - `alert_id` | any | required.
  - `status` | enum | required.  Values: `queued`, `running`, `completed`, `partial`, `no_matches`, `failed`, `cancelled`.
  - `hold` | integer | required.
  - `signals` | integer | required.
  - `leads` | integer | required.
  - `settled_at` | any | required.
  - `error` | string or null | required.
  - `scrape_outcome` | any | required.
  - `created_at` | string | required.
  - `started_at` | any | required.
  - `completed_at` | any | required.

## Failures

| Status | Meaning |
| --- | --- |
| `400` | The request shape, a filter key, a value, a cursor or the enrichment mode was rejected. |
| `401` | The credential is missing, unknown or revoked. |
| `402` | The daily or the monthly contact credit cap is spent, or the free plan's lifetime pool is. |
| `429` | The key passed 300 requests a minute or 2 concurrent requests. |
| `503` | The data is unavailable for a short time. |

## Example

```bash
curl -sS -X POST "https://api.leadmcp.ai/v1/signals/collect" \
  -H "Authorization: Bearer lm_live_YOUR_API_KEY" \
  -H "LeadMCP-Version: 2026-09-19" \
  -H "Content-Type: application/json" \
  -d '{"kind":"linkedin_profile","target":"https://www.linkedin.com/in/example"}'
```

Response `202`:

```json
{
  "ok": true,
  "request_id": "req_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
  "release": "b_2026_09_15",
  "data": {
    "job": {
      "kind": "linkedin_profile",
      "target": "https://www.linkedin.com/in/example",
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "alert_id": null,
      "status": "queued",
      "hold": 20,
      "signals": 0,
      "leads": 0,
      "settled_at": null,
      "error": null,
      "scrape_outcome": null,
      "created_at": "2026-09-19T09:15:00Z",
      "started_at": null,
      "completed_at": null
    }
  },
  "quota": {
    "plan": "free",
    "contact_credits_used": 50,
    "month_remaining": 950,
    "today_remaining": 950,
    "binding": "month",
    "resets_at": "9999-12-31T23:59:59.000Z"
  },
  "warnings": []
}
```