Skip to main content
GET
/
api
/
onboarding
/
status
Check onboarding scrape status
curl --request GET \
  --url https://app.puffle.ai/api/onboarding/status \
  --header 'Authorization: Bearer <token>'
{ "session": { "id": "7c2b2d4e-e29b-41d4-a716-446655440000", "status": "completed", "companyName": "Acme Inc", "errorMessage": null, "errorStep": null } }

​
Overview

Returns the latest onboarding_sessions row for the authenticated user, or null if the user has never started onboarding. The session.status field is the single source of truth for whether the workspace is ready:
StatusMeaning
pendingSession created; scrape has not started yet
looking_upResolving the domain / hitting Firecrawl
gathering_infoCrawling pages (up to 10)
generating_contextRunning the three parallel Sonnet generations
completedWorkspace is ready. company_context, market_context, and ICP are populated
failedScrape errored. errorMessage and errorStep describe where

​
AI agent notes

This is call #1 in the agent boot sequence. Every agent must start here.Do not call any other endpoint until you have confirmed session.status === "completed". The full boot sequence is documented in the Agent Playbook — GET /api/onboarding/status first, then GET /api/context to load the user’s company and ICP profile, then branch into one of the core journeys.If the response is { "session": null } — the user has never started onboarding. Stop and escalate to the human; there is no ICP, no company context, and every downstream call (lead search, campaign creation, deep research) will produce garbage.If status === "failed" — stop and report errorMessage / errorStep to the human. Do not retry blindly; the scrape usually fails because of a bad website URL, which a human has to fix.If status is a transient state (pending, looking_up, gathering_info, generating_context) — poll this endpoint every 3 to 5 seconds. A typical scrape completes in 30 to 90 seconds.No side effects. Safe to call as often as needed. Respect the 100 req per minute global rate limit.
See also: Start the onboarding scrape · Regenerate context · Agent Playbook.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
sessionId
string<uuid>

Specific onboarding session to inspect. Omit to fetch the most-recent session for the authenticated user.

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

Latest (or specified) onboarding session. session is null when the user has no session yet.

Response envelope. The session field is the single source of truth for workspace readiness.

​
session
object
required

Represents the latest onboarding scrape session for the authenticated user.