Skip to main content

Report Pipeline

This guide covers everything that happens after you confirm the accounts of a report: monitoring progress, the readiness check, and reading the report. These steps are the same for every report. Creating the report and choosing its accounts is described in the People search guide; the older per-network flow is in Classic search (deprecated).

Pipeline Overview​

Confirm Recap​

POST /create/{reportId}/confirm (signed-in account required) returns:

{
"estimatedTime": 240,
"loadTimeout": 150,
"loads": [
{"type": "follows", "status": "inprogress", "id": "123456789", "source": "ig"}
]
}
  • estimatedTime - seconds until the data is expected to be ready (0 = nothing to wait for)
  • loadTimeout - the time limit for loading, also in seconds
  • loads - the state of each account that is loading or failed, as the SSE stream reports it (People search reports only)

Important Notes​

  • Confirming does not consume a report credit. The credit check happens when the report is created (POST /create returns 402 if you have none). The credit is spent the first time the report's owner reads the finished report (GET /report/{reportId}), transparently, with no separate step.
  • A second read does not spend again.
  • Repeating the confirm returns 409 with "report profiles were already confirmed"; the earlier selection is left untouched.
  • If estimatedTime > 0, wait before fetching the report.
  • If a load fails (status: "error"), the account cannot be part of the report. See Profile Loading Errors.

Monitor Progress​

Check Status​

GET /check/{reportId}
{
"generated": false,
"ready": true,
"hasSource": true
}
FieldMeaning
generatedThe report is tracked: the owner has read it once. It does not mean the AI summary is ready.
readyThe data is loaded and the report can be read. Present while the report is unfinished and, for a finished report, when you may see its load detail.
inProgresstrue while an account is still loading. Omitted when false.
hasSourcetrue when at least one account is ready to build from.
loadError, errorSourceSet when an account failed to load: the reason (same codes as badReason) and the network.
owned, isDemo, publicPresent once the report is finished (generated: true).

How GET /check/{reportId} answers:

  • A caller who is not the owner of an unfinished report gets 200 {"generated": false}.
  • A malformed or unknown report ID gets 200 {"generated": true}; do not use that as proof the report exists.
  • 404 is returned when the caller has no access to the report (or it was deleted), so a report ID is never confirmed to someone who may not see it.
  • A chat-agent consumer (header X-SP-Report-Check-Consumer: chat-agent) gets 409 while the report is not finished.

The AI summary has its own readiness: the SSE summary event, then GET /report/{reportId}/summary.

Real-time Updates (SSE)​

Connect to SSE for live updates:

GET /sse/{reportId}

See the Real-time Updates Guide for the events and client code.

Read the Report​

Report page (slim, default)​

GET /report/{reportId}

Returns the slim ReportPage:

  • profiles: one row per network with identity, categoriesCount, totalInterests and topInterests
  • highlights: merged top categories, top interests and red-zone interests
  • redFlags: aggregated red-flag interests
  • friendsPreview: the first page of friends across networks
  • interestCategoriesPreview: truncated category trees per network
  • selectedProfiles when the report carries accounts it was not built from (for example a LinkedIn pick or a phone lookup's selection), each marked with isReportSubject

Heavy lists are separate calls (below).

Full interest categories (lazy-loaded detail)​

GET /report/{reportId}/interests
# Optional: one network only
GET /report/{reportId}/interests?source=ig

Full report shape (monolithic JSON)​

GET /report/{reportId}/full

Returns the full per-profile items. Its embedded summary is deprecated: use GET /report/{reportId}/summary instead.

Report for a specific source​

GET /report/{reportId}/{source}

Sorting options​

GET /report/{reportId}?sortByRedFlags=true&limit=50

Additional data endpoints​

# Friends, unified and per network
GET /report/{reportId}/friends?limit=24&offset=0
GET /report/{reportId}/friends/{source}?limit=24&offset=0

# Common interests with a friend
GET /report/{reportId}/{source}/common/{friendId}

# Interest details and the profiles that carry the interest
GET /report/{reportId}/{source}/{interestId}
GET /report/{reportId}/{source}/{interestId}/profiles

# Interest changes over time
GET /report/{reportId}/{source}/diffs?date=2024-01&type=new

# AI summary (generated asynchronously)
GET /report/{reportId}/summary

The summary is generated after the data loads. Wait for the SSE summary event with status: "done", then fetch it; the event never carries the summary itself.

Caching​

Report responses carry an ETag. Send it back as If-None-Match to revalidate: an unchanged report answers 304. A regenerated summary changes the ETag, so a client that revalidates always sees the new one.

Error Handling​

Repeat Confirm​

{
"code": 409,
"message": "report profiles were already confirmed"
}

A separate 403 "report was already generated" means the report has been built and can no longer be edited; it is distinct from the 409 above.

Report Limit Exceeded​

{
"code": 402,
"message": "to continue please upgrade your subscription"
}

POST /create (not confirm) returns 402 when you have no remaining report credits. A guest session gets "You have reached search limit. Please Sign up to continue." instead. If the credits run out before you read the finished report, the report page returns blurred placeholder data instead of an error.

Report Not Found​

{
"code": 404,
"message": "report not found"
}

The report ID does not exist or is not yours to read.

Best Practices​

  1. Cache the token - Don't authenticate on every request
  2. Use SSE for real-time updates - More efficient than polling
  3. Handle partial results - Some accounts may fail to load while others succeed
  4. Store report IDs - Reports can be retrieved later without re-creation
  5. Revalidate with If-None-Match - Cheaper than downloading an unchanged report