Skip to main content
GET
/
api
/
enrichment
/
{id}
Get Enrichment Run Status
curl --request GET \
  --url https://app.puffle.ai/api/enrichment/{id} \
  --header 'Authorization: Bearer <token>'
{
  "run": {
    "id": "<string>",
    "status": "<string>",
    "mode": "<string>",
    "enrichment": {
      "id": "<string>",
      "slug": "<string>",
      "version": 0,
      "snapshot": "<unknown>"
    },
    "scope": {
      "type": "<string>",
      "listId": "<string>",
      "requested": "<unknown>",
      "resolvedCount": 0,
      "counts": {
        "pending": 0,
        "running": 0,
        "completed": 0,
        "skipped": 0,
        "failed": 0
      }
    },
    "output": {
      "target": "<string>",
      "attributeKey": "<string>",
      "writePolicy": "<string>",
      "persistResults": true
    },
    "cost": {
      "preview": "<unknown>",
      "actual": "<unknown>"
    },
    "trigger": {
      "correlationId": "<string>",
      "triggerRunId": "<string>",
      "dispatchMetadata": "<unknown>"
    },
    "error": {
      "message": "<string>",
      "details": "<unknown>"
    },
    "timing": {
      "startedAt": "<string>",
      "completedAt": "<string>",
      "cancelledAt": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  }
}
CLI: 
puffle enrichment status --id <id>

​
Overview

Returns the status ledger for one Enrichment Run. This is the polling endpoint after Enrich leads — call it on an interval until status is terminal, then read per-Lead detail with Get enriched leads. The response is scoped to the effective user. Impersonating admins see only their effective user’s work, not the entire workspace.

​
Status lifecycle

pending → running → completed
                  ↘ failed
                  ↘ cancelled
  • pending — accepted, waiting for the worker.
  • running — worker is processing items.
  • completed — every item reached a terminal state.
  • failed — the worker errored out; check items for per-Lead reasons.
  • cancelled — explicitly stopped via Cancel enrichment; pending items are skipped.
See also: Enrich leads · Get enriched leads · Cancel enrichment.

​
AI agent notes

Use this endpoint to poll until the Enrichment Run is terminal. For per-Lead values — what succeeded, what failed, what the actual enriched output is — call Get enriched leads with the same id.Polling cadence: every 2 to 5 s while status is pending or running. Most Enrichment Runs complete within seconds to a few minutes; complex web-research jobs can take longer. Give up at 10 minutes and escalate with trigger.triggerRunId.Response shape: { run: { id, status, mode, enrichment, scope, output, cost, trigger, error, timing } }. Use run.scope.resolvedCount for the planned Lead count, run.enrichment.id or run.enrichment.slug for the Enrichment definition, run.trigger.triggerRunId for Trigger.dev correlation, and run.timing.* for created, updated, completed, and cancelled timestamps. Treat unknown fields as additive.On 404: the Enrichment Run does not exist for the effective user.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string
required
Minimum string length: 1

Response

Enrichment Run status.

​
run
object
required

Canonical Enrichment Run ledger row.