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

# Get Sourcing Results

> Returns the current state of a sourcing run. Responds with 202 and status 'processing' while in progress, or 200 with the full ranked candidate list (or error details) when completed.

Returns the current state of a sourcing run. While the run is in progress the response is `202 Accepted` with `status: "processing"`. Once finished it becomes `200 OK` with the full ranked candidate list (or error details if the run failed).

## Overview

Use this endpoint to poll for results when you do not have a webhook endpoint configured. The `requestId` is the value returned by [POST /sourcing](/api-reference/sourcing/initiate-sourcing).

## Polling Strategy

<Warning>
  Poll at most once every 5 seconds. Exceeding 120 requests per minute on this endpoint will trigger `429 RATE_LIMIT_EXCEEDED`.
</Warning>

```javascript theme={null}
async function waitForSourcingResults(requestId) {
  const url = `https://api.instaview.sk/sourcing/${requestId}/results`;
  const headers = { Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}` };

  while (true) {
    const res = await fetch(url, { headers });
    const body = await res.json();

    if (body.status === 'completed') return body.candidates;
    if (body.status === 'failed') throw new Error(`Sourcing failed: ${body.errorMessage}`);

    await new Promise(r => setTimeout(r, 5000));
  }
}
```

## Response Examples

### Still Processing (202 Accepted)

```json theme={null}
{
  "success": true,
  "requestId": "req_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "processing",
  "candidatesSourcedCount": 8,
  "message": "The sourcing agent is actively analyzing candidates. Please poll again in 5 seconds.",
  "createdAt": "2026-05-20T13:20:45.000Z"
}
```

### Completed (200 OK)

```json theme={null}
{
  "success": true,
  "requestId": "req_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "completed",
  "foundCount": 115,
  "scoredCount": 20,
  "createdAt": "2026-05-20T13:20:45.000Z",
  "completedAt": "2026-05-20T13:22:04.000Z",
  "candidates": [
    {
      "profileId": "prof_a9238f82-a723",
      "name": "Jane Doe",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe-ml",
      "matchScore": 96,
      "rationale": "Jane has over 6 years of experience leading ML Infrastructure. She has active contributions to vLLM, has fine-tuned LLaMA-based architectures, and is remote-compliant.",
      "headline": "Staff ML Infrastructure Engineer at TechCorp",
      "skills": ["vLLM", "PyTorch", "Kubernetes", "LLMs", "Vector Databases"],
      "location": "Seattle, WA, USA",
      "currentCompany": "TechCorp",
      "currentRole": "Staff ML Infrastructure Engineer",
      "aiFitPoints": [
        "Active open-source contributor to vLLM library",
        "Experience scaling agent architectures to 2M DAU at TechCorp"
      ],
      "aiRedFlags": [
        "Short average job tenure in pre-2022 startup roles"
      ],
      "aiDetailedRationale": [
        {
          "title": "Staff ML Infrastructure Engineer",
          "company": "TechCorp",
          "duration": "3.5 years",
          "relevanceExplanation": "LLM scaling & low-latency infrastructure, Kubernetes orchestration"
        }
      ],
      "detailedExperience": [
        {
          "role": "Staff ML Infrastructure Engineer",
          "company": "TechCorp",
          "duration": "2023 - Present",
          "highlights": [
            "Architected low-latency prompt caching server decreasing LLM inference cost by 42%.",
            "Deployed production-level multi-agent workflow system servicing 2M DAU."
          ]
        }
      ]
    }
  ]
}
```

### Failed (200 OK with `status: "failed"`)

```json theme={null}
{
  "success": true,
  "requestId": "req_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "failed",
  "errorCode": "PROVIDER_TEMPORARILY_UNAVAILABLE",
  "errorMessage": "External sourcing indexing platform returned a 503 after exhausting retries.",
  "createdAt": "2026-05-20T13:20:45.000Z",
  "completedAt": "2026-05-20T13:21:01.000Z"
}
```

## Multi-Tenant Isolation

If the `requestId` does not belong to the company associated with the authenticating API key, the API returns `404 REQUEST_NOT_FOUND`. This is intentional — it prevents adversarial probing of active execution queues.


## OpenAPI

````yaml GET /sourcing/{id}/results
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /sourcing/{id}/results:
    get:
      tags:
        - Public Sourcing
      summary: Get sourcing results
      description: >-
        Returns the current state of a sourcing run. Responds with 202 and
        status 'processing' while in progress, or 200 with the full ranked
        candidate list (or error details) when completed.
      operationId: PublicSourcingController_getSourcingResults_v1
      parameters:
        - name: id
          required: true
          in: path
          description: The requestId returned by POST /sourcing (e.g. req_550e8400-…).
          schema:
            type: string
      responses:
        '200':
          description: Sourcing results (completed or failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSourcingResultsResponseDto'
        '202':
          description: Sourcing run still in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSourcingResultsResponseDto'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Sourcing run not found or belongs to another company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
components:
  schemas:
    PublicSourcingResultsResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the response was successful.
          example: true
        requestId:
          type: string
          description: Unique external identifier for this sourcing run.
          example: req_550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: Current status of the run.
          enum:
            - processing
            - completed
            - failed
          example: completed
        candidatesSourcedCount:
          type: integer
          description: >-
            Running count of candidates found so far. Present when status =
            'processing'.
          example: 8
        foundCount:
          type: integer
          description: Total number of candidates found before scoring.
          example: 42
        scoredCount:
          type: integer
          description: Number of candidates that were AI-scored.
          example: 30
        message:
          type: string
          description: Human-readable status message. Present when status = 'processing'.
          example: >-
            The sourcing agent is actively analyzing candidates. Please poll
            again in 10 seconds.
        candidates:
          type: array
          description: Scored and ranked candidates. Present when status = 'completed'.
          items:
            $ref: '#/components/schemas/PublicSourcingCandidateDto'
        errorCode:
          type: string
          description: Machine-readable error code when status = 'failed'.
          example: AGENT_ERROR
        errorMessage:
          type: string
          description: Human-readable error message when status = 'failed'.
          example: The sourcing agent encountered an unexpected error.
        createdAt:
          type: string
          description: ISO 8601 timestamp when the run was created.
          example: '2025-01-01T00:00:00.000Z'
        completedAt:
          type: string
          description: ISO 8601 timestamp when the run completed or failed.
          example: '2025-01-01T00:01:30.000Z'
      required:
        - success
        - requestId
        - status
        - createdAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Validation failed
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
    PublicSourcingCandidateDto:
      type: object
      properties:
        profileId:
          type: string
          description: Opaque profile identifier (MD5 of LinkedIn URL).
          example: a1b2c3d4e5f6
        name:
          type: string
          description: Full name of the candidate.
          example: Jane Smith
        linkedinUrl:
          type: string
          description: LinkedIn profile URL.
          example: https://www.linkedin.com/in/janesmith
        matchScore:
          type: integer
          description: AI match score (0-100).
          example: 87
        rationale:
          type: string
          description: AI-generated rationale for the match.
          example: Strong fintech background with Node.js expertise.
        skills:
          type: array
          description: Primary skills extracted from the profile.
          items:
            type: string
          example:
            - Node.js
            - TypeScript
            - PostgreSQL
        headline:
          type: string
          description: Job headline or current title.
          example: Senior Software Engineer at Stripe
        location:
          type: string
          description: Candidate's location.
          example: San Francisco, CA
        currentCompany:
          type: string
          description: Candidate's current company.
          example: Stripe
        currentRole:
          type: string
          description: Candidate's current role/title.
          example: Senior Software Engineer
        aiFitPoints:
          type: array
          description: >-
            AI-generated fit points — specific reasons the candidate matches the
            role.
          items:
            type: string
          example:
            - 5+ years Node.js
            - FinTech background
        aiRedFlags:
          type: array
          description: AI-generated red flags or concerns about the candidate.
          items:
            type: string
          example:
            - No public cloud experience
        aiDetailedRationale:
          type: array
          description: AI-annotated relevant experience items from the candidate's history.
          items:
            $ref: '#/components/schemas/RelevantExperienceItem'
        detailedExperience:
          type: array
          description: >-
            Raw work history items scraped from the profile. Present after
            enrichment.
          items:
            $ref: '#/components/schemas/PublicDetailedExperienceItem'
        emails:
          type: array
          description: Discovered email addresses. Present after enrichment.
          items:
            type: string
          example:
            - jane.smith@example.com
      required:
        - profileId
        - name
    RelevantExperienceItem:
      type: object
      properties:
        title:
          type: string
          description: Job title
          example: Senior Developer
        company:
          type: string
          description: Company name
          example: Tech Corp
        duration:
          type: string
          description: Duration of the job
          example: 2 years
        relevanceExplanation:
          type: string
          description: Explanation of why this experience is relevant
          example: Led a team of 5 developers using Python/Django.
      required:
        - title
        - company
        - duration
        - relevanceExplanation
    PublicDetailedExperienceItem:
      type: object
      properties:
        role:
          type: string
          description: Job title / role.
          example: Staff ML Infrastructure Engineer
        company:
          type: string
          description: Company name.
          example: TechCorp
        duration:
          type: string
          description: Employment duration string.
          example: 2023 - Present
        highlights:
          type: array
          description: Notable accomplishments or responsibilities from this role.
          items:
            type: string
          example:
            - >-
              Architected low-latency prompt caching server decreasing LLM
              inference cost by 42%.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````