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

> Review saved Lead evaluations, including earlier decisions, and the exact signal findings and evidence behind each assessment.

Review the saved evaluations for one Lead. Each evaluation keeps its own assessment and the signal findings that support it, matching the portal's evaluation and Findings sections. Earlier evaluations keep their own qualification and score.

Use a Lead ID from [Leads](https://docs.plyne.ai/signals/leads.md). Compare an evaluation's `id` with the list record's `evaluation.id` to identify the selected evaluation. Results are ordered by evaluation saved time, newest first. An evaluated finding linked under another evaluation is shown within that evaluation's findings rather than repeated as a separate root evaluation.

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.plyne.ai/v1/leads/ld_example_01/evaluations/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": "eval_example_02",
      "found_at": "2026-11-16T09:42:43.119743Z",
      "source_sheet": {
        "id": "sh_example_01",
        "name": "Cloud infrastructure hiring"
      },
      "signal_agent_id": "ag_example_01",
      "qualification": {
        "status": "qualified",
        "reason": "Engineering role and backend hiring activity match the configured criteria.",
        "reasoning": "Jamie is an Engineering Manager at Stripe. The role and US location match the configured ideal customer profile, and a backend engineering opening matches the tracked hiring criteria.",
        "references": [
          {
            "type": "evidence",
            "label": "Senior Backend Engineer",
            "url": "https://example.com/jobs/senior-backend-engineer"
          },
          {
            "type": "evidence",
            "label": "Stripe",
            "url": "https://stripe.com"
          }
        ]
      },
      "ai_score": {
        "value": 82,
        "fit": "high",
        "reasoning": "The role and location match the configured criteria. The linked backend engineering opening adds relevant hiring context, resulting in a high fit score."
      },
      "findings": [
        {
          "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"
            }
          ]
        }
      ],
      "findings_cursor": {
        "next": "",
        "has_more": false
      }
    }
  ],
  "cursor": {
    "next": "",
    "has_more": false
  }
}
```

## Request fields

| Field | Location | Meaning |
| - | - | - |
| `lead_id` | Path | Required Lead ID. |
| `sheet_ids` | Body | Optional source Sheet filters for evaluations. |
| `found_at` | Body | Evaluation saved-time range; inclusive `start_time`, exclusive `end_time`. |
| `cursor.limit` | Body | Evaluation page size; default 50, maximum 100. |
| `cursor.after` | Body | The previous evaluation response's `cursor.next`. Keep the entity and filters unchanged. |

Send `{}` for the first page without filters. Older evaluations are included without a date filter. Results contain saved evaluations, not an immutable revision of every scheduled check.

## Continue reading linked findings

Each evaluation includes at most five visible findings in `findings`, newest saved first. When `findings_cursor.has_more` is true, use [Lead signal history](https://docs.plyne.ai/signals/lead-signals.md):

```json Linked-finding continuation theme={null}
{
  "evaluation_id": "EVALUATION_ID_FROM_YOUR_RESPONSE",
  "cursor": { "after": "FINDINGS_CURSOR_NEXT_FROM_YOUR_RESPONSE", "limit": 50 }
}
```

Keep `evaluation_id` fixed and leave other filters unset when continuing the embedded preview. Evaluation cursors and finding cursors are separate and cannot be interchanged.

An independently evaluated finding can appear as the evaluation's own finding. A combined evaluation can link several findings. No findings are attached by matching summaries, names, dates, or scores. Missing or hidden findings are not replaced with another source's data.

For all saved findings, including those outside an evaluation, use signal history without `evaluation_id`. For field definitions, see the [Data Dictionary](https://docs.plyne.ai/api/data-dictionary.md).


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