> ## 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.

# list signals

`GET /signals`

Returns signals newest first, with a cursor for the next page. The page size is at most 500. source_type and source_id read one source; a cursor from a filtered page keeps its filter. Reading is free: a row's contact was charged once, when the row was collected.

Returns signals newest first, with a cursor for the next page. The page size is at most 500. source_type and source_id read one source; a cursor from a filtered page keeps its filter. Reading is free: a row's contact was charged once, when the row was collected.

Cost: Free.

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `kind` | query | string | no |  |  |
| `alert_id` | query | string | no |  |  |
| `job_id` | query | string | no |  |  |
| `source_type` | query | enum | no |  | Reads one kind of source: alert or collect. |
| `source_id` | query | string | no |  | One alert id or collect job id. Send it only with source_type; alone it answers 400 request.invalid with field source_id. |
| `since` | query | string | no |  |  |
| `limit` | query | integer | no | 50 |  |
| `cursor` | query | string | no |  |  |

## Response

- `items` | array of object | required.
  - `id` | string | required.
  - `kind` | enum | required.  Values: `linkedin_engagement`, `company_follow`.
  - `action` | enum | required.  Values: `reaction`, `comment`, `follow`.
  - `subject` | string | required.
  - `seen_at` | string | required.
  - `source` | object | required.
    - `type` | enum | required.  Values: `alert`, `collect`.
    - `id` | string | required.
  - `linkedin_url` | string or null | required. The LinkedIn profile URL of the person who engaged or followed, as the source gave it. It is the key of the row and of the contact lookup.
  - `name` | string or null | required. The name the source shows for the person.
  - `headline` | string or null | required. The headline the source shows for the person.
  - `details` | any | required.
  - `contact` | any | required.
  - `contact_status` | enum | required. delivered: the LinkedIn URL matched a stored contact, one contact credit was charged, and contact holds it. not_found: no stored contact has this URL, or the URL is not a public profile URL; nothing was charged. credits_exhausted: a contact matched but the contact credit caps had no room; nothing was charged. account_blocked: a contact matched but the account could not be charged; nothing was charged. pending: the lookup has not run yet; nothing was charged. The lookup runs once, when the row is collected, so reading the feed again never charges again. Values: `delivered`, `not_found`, `credits_exhausted`, `account_blocked`, `pending`.
- `next_cursor` | string or null | 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. |
| `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 "https://api.leadmcp.ai/v1/signals" \
  -H "Authorization: Bearer lm_live_YOUR_API_KEY" \
  -H "LeadMCP-Version: 2026-09-19"
```

Response `200`:

```json
{
  "ok": true,
  "request_id": "req_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
  "release": "b_2026_09_15",
  "data": {
    "items": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
        "kind": "linkedin_engagement",
        "action": "comment",
        "subject": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890",
        "seen_at": "2026-09-20T00:00:00Z",
        "source": {
          "type": "collect",
          "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW"
        },
        "linkedin_url": "https://www.linkedin.com/in/example",
        "name": "Alex Morgan",
        "headline": "Engineering leader",
        "details": {
          "text": "Thanks for sharing.",
          "reaction_type": null
        },
        "contact": {
          "id": "per_01ARZ3NDEKTSV4RRFFQ69G5FAY",
          "name": "Alex Morgan",
          "title": "Engineering Director",
          "company": "Example",
          "company_domain": "example.com",
          "work_email": "alex@example.com",
          "country": "us",
          "seniority": "director",
          "last_updated": "2026-08",
          "mobile_phone": null,
          "direct_phone": null,
          "has_phone": false,
          "function": "engineering",
          "location": "Austin, Texas, United States",
          "email_status": "valid",
          "company_size": "201-500",
          "company_industries": [
            "software_development"
          ],
          "company_linkedin": "https://www.linkedin.com/company/example",
          "linkedin": "https://www.linkedin.com/in/example"
        },
        "contact_status": "delivered"
      },
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
        "kind": "linkedin_engagement",
        "action": "reaction",
        "subject": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890",
        "seen_at": "2026-09-20T00:00:00Z",
        "source": {
          "type": "collect",
          "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW"
        },
        "linkedin_url": "https://www.linkedin.com/in/someone-else",
        "name": "Sam Lee",
        "headline": null,
        "details": {
          "text": null,
          "reaction_type": "LIKE"
        },
        "contact": null,
        "contact_status": "not_found"
      }
    ],
    "next_cursor": 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": []
}
```