# Limit

Keep the first N records after an optional offset, overall or per group.

## When to use it

Take a bounded window after an optional offset, either overall or per group. Sort first if the meaning of “first” matters. This changes the records delivered downstream; it is separate from paging a viewer over already stored results.

## Add and configure

1. Add **Limit** from the workflow step picker.
2. Give the step a recognisable name and connect its required inputs.
3. Set the options below. Nested names identify fields within an object or a list item.
4. Validate the recipe, inspect the test result, then run it on the intended data.

The step identifier used in the editor’s code view is `limit`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Count (`count`) | integer; minimum 0 | Yes | Not specified | How many records to keep (per group with `per_group`). |
| Offset (`offset`) | integer; minimum 0 | No | 0 | How many records to skip first (per group with `per_group`). |
| Per Group (`per_group`) | list of string | No | Not specified | JSONPaths whose values together name a group; the offset and count then apply within each group. Empty: one group, the whole input. |

## Inputs and outputs

| Direction | Port | Content | Required | Multiple records |
| --- | --- | --- | --- | --- |
| Inputs | `in` | records | Yes | Yes |
| Outputs | `out` | records | Yes | Yes |

## Effects, testing, and recovery

Transforms or passes records without a declared external side effect.

The declared preview behaviour is to execute this step. Reads, processing, or model usage can therefore be real. Read [dry runs](/docs/workflows/dry-runs) before using a preview with live connections.

No duplicate-prevention key is declared for this step. The step declares safe replay for its supported recovery path.

## Example: Keep the first two

Step settings:

```json
{
  "count": 2
}
```

Input records:

```json
[
  {
    "n": 1
  },
  {
    "n": 2
  },
  {
    "n": 3
  }
]
```

Expected output for this example:

```json
[
  {
    "n": 1
  },
  {
    "n": 2
  }
]
```

## Example: The second page of two

Step settings:

```json
{
  "count": 2,
  "offset": 2
}
```

Input records:

```json
[
  {
    "n": 1
  },
  {
    "n": 2
  },
  {
    "n": 3
  },
  {
    "n": 4
  },
  {
    "n": 5
  }
]
```

Expected output for this example:

```json
[
  {
    "n": 3
  },
  {
    "n": 4
  }
]
```

## Example: At most one record per topic

Step settings:

```json
{
  "count": 1,
  "per_group": [
    "$.topic"
  ]
}
```

Input records:

```json
[
  {
    "title": "a1",
    "topic": "ai"
  },
  {
    "title": "a2",
    "topic": "ai"
  },
  {
    "title": "s1",
    "topic": "space"
  }
]
```

Expected output for this example:

```json
[
  {
    "title": "a1",
    "topic": "ai"
  },
  {
    "title": "s1",
    "topic": "space"
  }
]
```

## Check the result

Inspect the selected run’s status, counts, errors, and output records. An empty collection can be a valid result, and a completed step can contain per-record failures where the step defines that behaviour. Check the next step’s expected record shape before publishing or delivering the result.