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 secondsloads- 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 /createreturns402if 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
409with"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
}
| Field | Meaning |
|---|---|
generated | The report is tracked: the owner has read it once. It does not mean the AI summary is ready. |
ready | The 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. |
inProgress | true while an account is still loading. Omitted when false. |
hasSource | true when at least one account is ready to build from. |
loadError, errorSource | Set when an account failed to load: the reason (same codes as badReason) and the network. |
owned, isDemo, public | Present 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. 404is 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) gets409while 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,totalInterestsandtopInterestshighlights: merged top categories, top interests and red-zone interestsredFlags: aggregated red-flag interestsfriendsPreview: the first page of friends across networksinterestCategoriesPreview: truncated category trees per networkselectedProfileswhen the report carries accounts it was not built from (for example a LinkedIn pick or a phone lookup's selection), each marked withisReportSubject
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
- Cache the token - Don't authenticate on every request
- Use SSE for real-time updates - More efficient than polling
- Handle partial results - Some accounts may fail to load while others succeed
- Store report IDs - Reports can be retrieved later without re-creation
- Revalidate with
If-None-Match- Cheaper than downloading an unchanged report