Skip to main content
GET
/
sourcing
/
preview
/
{id}
/
results
Get sourcing preview results
curl --request GET \
  --url https://api.instaview.sk/sourcing/preview/{id}/results \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "requestId": "req_prev_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "candidatesSourcedCount": 8,
  "foundCount": 42,
  "scoredCount": 30,
  "message": "The sourcing agent is actively analyzing candidates. Please poll again in 10 seconds.",
  "candidates": [
    {
      "profileId": "a1b2c3d4e5f6",
      "fullName": "Jane Smith",
      "profileUrl": "https://www.linkedin.com/in/janesmith",
      "title": "Senior Software Engineer",
      "headline": "Senior Software Engineer at Stripe",
      "location": "San Francisco, CA",
      "country": "United States",
      "companyName": "Stripe",
      "companyUrl": "https://www.linkedin.com/company/stripe"
    }
  ],
  "errorCode": "AGENT_ERROR",
  "errorMessage": "The sourcing agent encountered an unexpected error.",
  "completedAt": "2025-01-01T00:01:30.000Z"
}
Returns the current state of a sourcing preview run. While the run is in progress the response is 202 Accepted with status: "processing". Once finished it becomes 200 OK with the candidate preview list (or error details if the run failed).

​
Overview

Use this endpoint to poll for preview results when you do not have a webhook configured. The requestId is the value returned by POST /sourcing/preview.

​
Polling Strategy

Poll at most once every 10 seconds. Exceeding 120 requests per minute on this endpoint will trigger 429 RATE_LIMIT_EXCEEDED.
async function waitForPreviewResults(requestId) {
  const url = `https://api.instaview.sk/sourcing/preview/${requestId}/results`;
  const headers = { Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}` };

  while (true) {
    const res = await fetch(url, { headers });
    if (res.status === 429) {
      const retryAfter = Number(res.headers.get("Retry-After") ?? 10);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }
    if (!res.ok)
      throw new Error(`Preview polling failed with status ${res.status}`);
    const body = await res.json();

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

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

​
Response Examples

​
Still Processing (202 Accepted)

{
  "success": true,
  "requestId": "req_prev_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "processing",
  "candidatesSourcedCount": 12,
  "message": "The sourcing agent is actively analyzing candidates. Please poll again in 10 seconds.",
  "createdAt": "2026-06-11T19:50:45.000Z"
}

​
Completed (200 OK)

{
  "success": true,
  "requestId": "req_prev_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "completed",
  "foundCount": 20,
  "scoredCount": 20,
  "createdAt": "2026-06-11T19:50:45.000Z",
  "completedAt": "2026-06-11T19:51:02.000Z",
  "candidates": [
    {
      "profileId": "prof_a9238f82-a723",
      "fullName": "Jane Doe",
      "profileUrl": "https://www.linkedin.com/in/janedoe-ml",
      "title": "Staff ML Infrastructure Engineer",
      "headline": "Staff ML Infrastructure Engineer at TechCorp",
      "location": "Seattle, WA, USA",
      "country": "United States",
      "companyName": "TechCorp",
      "companyUrl": "https://www.linkedin.com/company/techcorp"
    }
  ]
}

​
Failed (200 OK with status: "failed")

{
  "success": true,
  "requestId": "req_prev_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "failed",
  "errorCode": "PROVIDER_TEMPORARILY_UNAVAILABLE",
  "errorMessage": "External sourcing indexing platform returned a 503 after exhausting retries.",
  "createdAt": "2026-06-11T19:50:45.000Z",
  "completedAt": "2026-06-11T19:51:01.000Z"
}

​
Multi-Tenant Isolation

If the requestId does not belong to the company associated with the authenticating API key, or if the request ID format does not match a preview run, the API returns 404 REQUEST_NOT_FOUND or 400 BAD_REQUEST.

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

​
id
string
required

The requestId returned by POST /sourcing/preview (e.g. req_prev_550e8400-…).

Pattern: ^req_prev_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Response

Sourcing preview results (completed or failed)

​
success
boolean
required

Whether the response was successful.

Example:

true

​
requestId
string
required

Unique external identifier for this sourcing run.

Example:

"req_prev_550e8400-e29b-41d4-a716-446655440000"

​
status
enum<string>
required

Current status of the run.

Available options:
processing,
completed,
failed
Example:

"completed"

​
createdAt
string
required

ISO 8601 timestamp when the run was created.

Example:

"2025-01-01T00:00:00.000Z"

​
candidatesSourcedCount
integer

Running count of candidates found so far. Present when status = 'processing'.

Example:

8

​
foundCount
integer

Total number of candidates found before scoring.

Example:

42

​
scoredCount
integer

Number of candidates that were AI-scored.

Example:

30

​
message
string

Human-readable status message. Present when status = 'processing'.

Example:

"The sourcing agent is actively analyzing candidates. Please poll again in 10 seconds."

​
candidates
object[]

Scored and ranked candidates. Present when status = 'completed'.

​
errorCode
string

Machine-readable error code when status = 'failed'.

Example:

"AGENT_ERROR"

​
errorMessage
string

Human-readable error message when status = 'failed'.

Example:

"The sourcing agent encountered an unexpected error."

​
completedAt
string

ISO 8601 timestamp when the run completed or failed.

Example:

"2025-01-01T00:01:30.000Z"