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

# Searches and shortlists

> How a search runs, what its outcome means, and how to get more people without starting over.

> Agents: the full documentation index is at [/llms.txt](https://docs.revcenter.ai/llms.txt).

## How a search runs

1. **Your workspace's candidates first.** People already in your workspace who match are scored before
   anything new is read. If they meet the target, the search stops there.
2. **LinkedIn.** The search reads LinkedIn with your filters, page by page.
3. **Profiles and scoring.** Matching profiles are read and scored against your criteria.
4. **Shortlist.** Everyone at or above the cut-off (80 by default) goes on the project's shortlist.

Each search has a spending ceiling, and it stops early if it is no longer finding people who fit. Poll
`GET /v1/searches/{id}` (or `revcenter status <id> --wait`): `status` moves from `running` to `complete`, and
`stage` shows where it is. See [async jobs](/guides/async-jobs) for every status.

## Outcomes

A finished search reports its outcome by how many people it delivered:

| Outcome | Delivered |
| - | - |
| Shortlist ready | 6 or more |
| Poor yield | 1 to 5 |
| No results | 0 |

The outcome is fixed when the search finishes. Changes you make afterwards (rescoring, adding or removing
people) change the shortlist, not the outcome.

## Getting more people

| Option | What it does | Credits |
| - | - | - |
| **Rescore** | Change the cut-off, weights or requirements for everyone already read. Preview first. | Does not use shortlist credits. |
| **Search your database** | Score your workspace's candidates on file against this search again. | Does not use shortlist credits. |
| **Expand** | A new live pass on the same role, skipping everyone already found. Up to 2 per project. | Uses 1 shortlist credit per expansion. |
| **Database-only search** | A new search of your workspace's candidates only (`database_only: true`). | Does not use shortlist credits. |

Titles and places can't be rescored: they decide who is found, so changing them needs a new search.

## Scored people

`GET /v1/searches/{id}/people` returns everyone the search scored, best first (see [pagination](/guides/pagination)).
Each person has a `score` from 0 to 100 and `fit`, the readings behind it. `fit` holds only the readings the
scorer recorded for that person, from: `title_match`, `geo_fit`, `years_fit`, `seniority_fit`, `skills_match`,
`industry_match`, `must_have_coverage`, `tier`, `qualified` and `reject_code`.

## The shortlist

`GET /v1/projects/{id}/shortlist` returns everyone on it, best first, each with their score, how they fit each
criterion, and their full profile: every role with dates and description, schools, skills, certifications,
languages and projects. `GET /v1/projects/{id}/shortlist.csv` has the same in a spreadsheet, plus the profile as
JSON in its last column. Contact details are not part of API exports.


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