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

# Lead Signal History

> Read the saved signal findings for a specific Lead, including older findings, source links, and any qualification or AI score recorded for each finding.

```http theme={null}
POST /v1/leads/{lead_id}/signals/search
```

Review saved findings for one Lead, including earlier results. Each finding includes its own available evidence and assessment.

Use the Lead `id` returned by [Leads](https://docs.plyne.ai/signals/leads.md) in the URL. Results are ordered by when the finding was saved, newest first. Leave the date filter unset to include earlier findings, or narrow results by signal type, Sheet, and date.

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.plyne.ai/v1/leads/ld_example_01/signals/search' \
  --header 'Authorization: Bearer plyne_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "cursor": {
      "limit": 50
    }
  }'
```

The people, hiring events, and assessments in this response are illustrative.

```json 200 theme={null}
{
  "data": [
    {
      "id": "sig_example_02",
      "type": "hiring_signals",
      "name": "Hiring Activity",
      "summary": "Stripe has an open Senior Backend Engineer role in this example.",
      "reason": "The backend engineering opening matches the tracked hiring criteria and provides context for contacting an engineering decision-maker.",
      "found_at": "2026-11-16T09:42:43.119743Z",
      "observed_at": "2026-11-16T09:42:43.119743Z",
      "source_sheet": {
        "id": "sh_example_01",
        "name": "Cloud infrastructure hiring"
      },
      "signal_agent_id": "ag_example_01",
      "qualification": null,
      "ai_score": null,
      "references": [
        {
          "type": "evidence",
          "label": "Senior Backend Engineer",
          "url": "https://example.com/jobs/senior-backend-engineer"
        }
      ]
    }
  ],
  "cursor": {
    "next": "",
    "has_more": false
  }
}
```

The example shows a qualified Lead whose individual hiring finding has `qualification: null` and `ai_score: null`. The Lead assessment and the finding assessment are separate; the history endpoint preserves the finding's own saved values.

## Path and body fields

| Field | Location | Meaning |
| - | - | - |
| `lead_id` | Path | Required Lead ID. |
| `evaluation_id` | Body | Optional exact evaluation ID. Returns only that evaluation’s visible linked findings. |
| `signal_types` | Body | Optional stable signal type IDs. |
| `sheet_ids` | Body | Optional source Sheet IDs. |
| `found_at` | Body | Optional Date found range for saved signal findings. |
| `cursor.limit` | Body | Page size; default `50`, maximum `100`. |
| `cursor.after` | Body | `cursor.next` from the previous response. |

Send `{}` to request the first page without filters. Omitting `found_at` includes all retained history; there is no implicit recent-date window. Historical records already stored in Plyne are readable without rerunning a Signal Agent.

## What history contains

History uses the same saved signal findings as the portal. It includes qualified, unqualified, and unclear findings. The `qualification` and `ai_score` describe the saved finding, rather than replacing it with today's lead decision. `ai_score` is `null` if no score was calculated.

Imports and aggregate qualification decision cards are excluded from signal history. Deleted records, hidden source Sheets, and disliked entities are excluded. Results are scoped to the workspace that owns the API key.

`found_at` is when Plyne saved the signal occurrence and is used for filtering and ordering. `observed_at`, when available, is the source evidence's observation time; otherwise it is `null`. These timestamps can differ. `references` contains the available source links.

History is a sequence of retained signal findings, not an audit log of every agent check or every historical version of an updated finding. If repeat checks were combined into an existing occurrence, they remain one entry.

## Pagination

Use `cursor.next` as `cursor.after` to request another page. Keep the same Lead, filters, and workspace. See [Pagination and Filters](https://docs.plyne.ai/api/pagination.md) for page limits and cursor behavior.

## Findings behind a decision

Use `evaluation_id` to read findings linked to one saved evaluation. This preserves the portal’s decision-to-finding relationship. To browse the evaluations themselves, use [Lead evaluations](https://docs.plyne.ai/signals/lead-evaluations.md).

A finding keeps its own assessment. An evaluation's qualification is never substituted for the finding's qualification. When continuing an embedded `findings_cursor`, keep the evaluation ID fixed and leave other filters unset. Without `evaluation_id`, this endpoint returns all visible saved findings for the record.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.