> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Loops

> Start, inspect, and observe ontology-guided loop runs over Penumbra context.

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`](/sdk/loops). Use the REST API when you need direct
HTTP access or want to inspect the request and response shape.

<Info>
  Executing a loop consumes Penumbra credits. `dry_run` compiles the loop without
  starting execution or spending credits.
</Info>

## Start a loop

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

| Kind               | Use it for                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `graph_extraction` | Extract typed entities and relationships from source context into one or more shapes.         |
| `hydrate`          | Build enough graph context around a subject or purpose to make downstream work fit to act on. |

## Effort

| Effort         | Use it for                                                                        |
| -------------- | --------------------------------------------------------------------------------- |
| `agentic`      | Default managed loop execution.                                                   |
| `agentic_plus` | More intensive managed loop execution for harder corpora or stricter review bars. |

## Errors

Common loop errors:

| Error                           | Meaning                                                           |
| ------------------------------- | ----------------------------------------------------------------- |
| `unsupported_loop_kind`         | `kind` must be `graph_extraction` or `hydrate`.                   |
| `unsupported_loop_effort`       | `effort` must be `agentic` or `agentic_plus`.                     |
| `apply_not_supported_for_loops` | Loops stage deltas. Apply the delta after review.                 |
| `credits_exhausted`             | The organization does not have enough credits to start execution. |
| `loop_dispatch_unavailable`     | Loop 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`.