Skip to main content
GET
/
api
/
v1
/
research
/
{id}
Get research status and report (partner API)
curl --request GET \
  --url https://app.puffle.ai/api/v1/research/{id} \
  --header 'Authorization: Bearer <token>'
{
  "person": {
    "id": "11111111-1111-1111-1111-111111111111",
    "user_id": null,
    "first_name": "Jane",
    "last_name": "Smith",
    "linkedin_url": "https://www.linkedin.com/in/janesmith",
    "role": "VP of Engineering",
    "company": "Acme Corp",
    "company_domain": "acme.com",
    "photo_url": null,
    "status": "complete",
    "last_enriched_at": "2026-04-21T18:00:00Z",
    "created_at": "2026-04-21T17:55:00Z",
    "updated_at": "2026-04-21T18:00:00Z"
  },
  "status": "complete",
  "report": {
    "summary": "Jane Smith is VP of Engineering at Acme Corp...",
    "icp_score": 91
  },
  "change_summary": null
}

​
Overview

The canonical polling endpoint for partner research. Returns the person row, current status, and (when status === "complete") the highest-version report content inline. Requires partner authentication. User Bearer tokens are rejected.

​
Response shape

The GET response envelope matches createResearchV1 exactly:
  • person — the full person row (identity, status, timestamps)
  • status — duplicated at top level for convenience
  • report — JSON report content, or null when pipeline hasn’t completed
  • change_summary — human-readable diff vs prior version, or null
This operation shares the URL path /api/v1/research/{id} with the delete verb. See Delete research (partner API) to permanently remove a research person and every cascaded artifact.

​
AI agent notes

Polling cadence: every 30 seconds after a createResearchV1 that returned 202. Typical pipeline duration is 1 to 5 minutes.Terminal signals — stop polling when you see any of:
  • status === "complete" with report attached (done — present the report)
  • status === "failed" (retry by re-submitting the same linkedin_url via createResearchV1, which auto-flips failed to running)
  • More than 10 minutes have elapsed without completion (treat as stuck; re-submit via createResearchV1)

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

Deep research person UUID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

Person plus report when complete. report is null while the pipeline is still running.

The canonical partner-API envelope for a single research person. Same shape is returned by createResearchV1, getResearchV1, and the duplicate-return path of createResearchV1.

​
person
object
required

A person tracked for deep research. The row is created first; enrichment + report generation happen asynchronously in a Trigger.dev pipeline.

​
status
enum<string>
required

Lifecycle of a deep research person. idle is a fresh row with no run in flight; running means a Trigger.dev pipeline is active; complete means the latest report is ready; failed means the pipeline errored and the row is retry-eligible.

Available options:
idle,
running,
complete,
failed
​
report
object
required

Report body — a JSON object with summary, background, company intel, outreach angles, and source citations. Shape evolves; treat fields defensively.

​
change_summary
string | null
required

Human-readable diff vs the prior version. Null on first version or when no report exists.