> ## 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. # Get a search > The full state of one search: the record itself, per-stage run history, and ranked candidates. Client-mode searches additionally return discovered companies and decision-maker leads. Poll this while `scan.status` is `running`. ## OpenAPI ````yaml /openapi.json get /api/scans/{id} openapi: 3.1.0 info: title: Revcenter API description: >- Search, enrich, and activate people and companies. Two authentication surfaces share one host: the bearer-token API under `/v1` for server-to-server and agent use, and the workspace-session API under `/api` that the Revcenter app itself runs on. version: '2026-08-12' servers: - url: https://api.revcenter.ai description: Production security: - bearerAuth: [] tags: - name: Search description: Web search, search runs, results, exports, and shareable shortlists. - name: People description: Person search, profile enrichment, and the workspace contact pool. - name: Companies description: Company search, company enrichment, and org-chart people. - name: Campaigns description: Plan, publish, and launch outbound sequences on Smartlead and HeyReach. - name: Account description: Health, usage totals, and cost events. paths: /api/scans/{id}: get: tags: - Search summary: Get a search description: >- The full state of one search: the record itself, per-stage run history, and ranked candidates. Client-mode searches additionally return discovered companies and decision-maker leads. Poll this while `scan.status` is `running`. operationId: getScan parameters: - $ref: '#/components/parameters/ScanId' responses: '200': description: The search, its runs, and its results. content: application/json: schema: type: object properties: scan: $ref: '#/components/schemas/Scan' runs: type: array items: $ref: '#/components/schemas/Run' candidates: type: array items: $ref: '#/components/schemas/ScoredCandidate' companies: type: array items: type: object additionalProperties: true description: Client-mode only. clientLeads: type: array items: type: object additionalProperties: true description: Client-mode only. access: type: object properties: canShare: type: boolean '401': $ref: '#/components/responses/AppUnauthorized' '404': $ref: '#/components/responses/AppNotFound' '502': $ref: '#/components/responses/AppUpstreamError' security: - sessionCookie: [] components: parameters: ScanId: name: id in: path required: true description: The search ID. schema: type: string format: uuid schemas: Scan: allOf: - $ref: '#/components/schemas/ScanSummary' - type: object properties: mode: $ref: '#/components/schemas/ScanMode' criteria: $ref: '#/components/schemas/Criteria' qualified: type: - integer - 'null' description: How many results cleared the qualification bar. quality_report: type: - object - 'null' additionalProperties: true Run: type: object description: >- One stage of the pipeline. The sequence is the audit trail for how a search reached its results. properties: id: type: string stage: type: string examples: - serp status: type: string examples: - complete items_in: type: - integer - 'null' items_out: type: - integer - 'null' error: type: - string - 'null' started_at: type: - string - 'null' format: date-time finished_at: type: - string - 'null' format: date-time ScoredCandidate: type: object properties: rank: type: - integer - 'null' score: type: - number - 'null' description: 0–100. Only 80+ is shareable. subscores: type: - object - 'null' description: Per-dimension breakdown behind the score. additionalProperties: true phase: type: - string - 'null' verdict: type: - string - 'null' enum: - accept - reject - maybe - null candidate: $ref: '#/components/schemas/Candidate' ScanSummary: type: object properties: id: type: string format: uuid title: type: - string - 'null' status: $ref: '#/components/schemas/ScanStatus' sector: type: - string - 'null' pulled: type: - integer - 'null' description: How many results have been pulled so far. target_count: type: - integer - 'null' raw_input: type: - string - 'null' created_at: type: string format: date-time closed_at: type: - string - 'null' format: date-time error: type: - string - 'null' ScanMode: type: string enum: - candidate - client default: candidate description: >- `candidate` searches for people against a role. `client` discovers target companies first, then their decision-makers. Criteria: type: object description: >- The structured brief a search runs on. Every field is optional, but a search with no signal finds nothing useful. The distinction that matters: `exclude_*` fields are hard and disqualify, while `avoid_*` fields are soft and only rank down. A great person at a firm you'd rather avoid still shows up; a person at an excluded firm never does. properties: family: type: string description: >- Role family from the taxonomy. Off-taxonomy roles are kept as a title variant instead. title_variants: type: array items: type: string description: >- Acceptable job titles. A quoted `title: "X"` in the brief always survives extraction and leads this list. seniority: type: string enum: - c_suite - vp - director - manager - ic allowed_seniority: type: array items: type: string enum: - c_suite - vp - director - manager - ic must_have: type: array items: type: string industries: type: array items: type: string metro: type: string examples: - San Jose, CA geo_radius_mi: type: number exclusiveMinimum: 0 description: >- Commute radius. Dropped automatically on country-level searches, where it is meaningless. remote_ok: type: boolean exclude_titles: type: array items: type: string description: Hard exclusion. exclude_industries: type: array items: type: string description: Hard exclusion. exclude_companies: type: array items: type: string description: >- Hard exclusion. Evaluated against search text too, so excluded people never reach paid enrichment. avoid_titles: type: array items: type: string description: Soft negative — ranks down, never rejects. avoid_industries: type: array items: type: string description: Soft negative. avoid_companies: type: array items: type: string description: Soft negative. comp_band: type: array items: type: number minItems: 2 maxItems: 2 years_experience: type: object properties: min: type: number max: type: number min_avg_tenure_years: type: number exclusiveMinimum: 0 skills: type: array items: type: string skills_required: type: array items: type: string languages_required: type: array items: type: string description: >- Hard requirement, kept separate from skills: holding a job title implies its competencies, but never implies a language. target_company_profile: type: object properties: sector: type: string employee_range: type: array items: type: number minItems: 2 maxItems: 2 pe_backed_preferred: type: boolean rubric_weights: type: object description: >- Relative emphasis per scoring dimension, compiled from what this brief stresses and locked to the run. The scorer clamps and renormalizes. properties: title: type: number years: type: number skills: type: number geo: type: number industry: type: number seniority: type: number Candidate: type: object properties: id: type: string firstName: type: - string - 'null' lastName: type: - string - 'null' roleTitle: type: - string - 'null' company: type: - string - 'null' metro: type: - string - 'null' profileUrl: type: - string - 'null' format: uri photoUrl: type: - string - 'null' format: uri headline: type: - string - 'null' email: type: - string - 'null' description: Populated only after contact enrichment. phone: type: - string - 'null' description: Populated only after contact enrichment. hydrated: type: - boolean - 'null' description: >- Whether the full profile was fetched, or only search-level data is known. signals: type: array items: type: object additionalProperties: true AppError: type: object description: >- The error shape used by every `/api` endpoint. Flatter than the `/v1` shape, and `code` appears only where the UI branches on it. properties: error: type: string code: type: string examples: - search_unavailable ScanStatus: type: string enum: - queued - running - complete - failed description: >- A run that produced results finishes `complete` even if a late stage errored — partial results are not thrown away. responses: AppUnauthorized: description: >- Not signed in, no active workspace, or the account lacks the role this action needs. A frozen account gets `403` with code `frozen`. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: signIn: value: error: Sign in required AppNotFound: description: >- The record does not exist, or belongs to another workspace. The two are deliberately indistinguishable. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: notFound: value: error: Scan not found AppUpstreamError: description: A downstream service or the database failed. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: upstream: value: error: Spec extraction failed securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Revcenter API key: `Authorization: Bearer rvc_live_...`. Keys are scoped, rate limited per key, and metered per workspace. sessionCookie: type: apiKey in: cookie name: session description: >- A signed-in workspace session, sent as a browser cookie. Requests must include credentials, and act on the session's active workspace. ````