Skip to main content
Loops are long-running agentic jobs. They run against source material and shapes, stage their output into a delta, and expose status, events, and checkpoints while the run executes. Most builders use pb.loops. Use the REST API when you need direct HTTP access or want to inspect the request and response shape.
Executing a loop consumes Penumbra credits. dry_run compiles the loop without starting execution or spending credits.

​
Start a loop

curl -X POST https://pnbr.io/v1/loops \
  -H "Authorization: Bearer $PENUMBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "graph_extraction",
    "project_id": "9142fa4d-7aad-4a1b-8f99-b522fd37518d",
    "goal": "Extract customers, initiatives, risks, and relationships from the account memo.",
    "context": { "source_ids": ["src_01JZ4..."] },
    "schema": { "shape_ids": ["shp_customer_intelligence"] },
    "loop": {
      "effort": "agentic",
      "max_iterations": 5,
      "quality_threshold": 8
    },
    "output": { "type": "delta", "apply": false }
  }'
A successful execution request returns 202 Accepted with a loop_id, a staged result delta_id, and links for polling, events, and checkpoints.

​
Read loop status

curl https://pnbr.io/v1/loops/$LOOP_ID \
  -H "Authorization: Bearer $PENUMBRA_API_KEY"
Use status to decide when to inspect the delta.

​
Read events

curl "https://pnbr.io/v1/loops/$LOOP_ID/events?limit=50" \
  -H "Authorization: Bearer $PENUMBRA_API_KEY"
Pass after_sequence to continue from the last event you processed.

​
Read checkpoints

curl https://pnbr.io/v1/loops/$LOOP_ID/checkpoints \
  -H "Authorization: Bearer $PENUMBRA_API_KEY"
Checkpoints expose iteration-level state for debugging, audit, and review.

​
Kinds

KindUse it for
graph_extractionExtract typed entities and relationships from source context into one or more shapes.
hydrateBuild enough graph context around a subject or purpose to make downstream work fit to act on.

​
Effort

EffortUse it for
agenticDefault managed loop execution.
agentic_plusMore intensive managed loop execution for harder corpora or stricter review bars.

​
Errors

Common loop errors:
ErrorMeaning
unsupported_loop_kindkind must be graph_extraction or hydrate.
unsupported_loop_efforteffort must be agentic or agentic_plus.
apply_not_supported_for_loopsLoops stage deltas. Apply the delta after review.
credits_exhaustedThe organization does not have enough credits to start execution.
loop_dispatch_unavailableLoop execution is temporarily unavailable.
The generated endpoint reference in the sidebar includes request and response schemas for /v1/loops, /v1/loops/{loop_id}, /v1/loops/{loop_id}/events, and /v1/loops/{loop_id}/checkpoints.