---
title: "List the items of a foreach step in a DAG-run"
method: GET
path: "/dag-runs/{name}/{dagRunId}/steps/{stepName}/foreach"
tags: ["dag-runs"]
---

# List the items of a foreach step in a DAG-run

`GET /dag-runs/{name}/{dagRunId}/steps/{stepName}/foreach`

## Request

- Base URL: `http://localhost/api/v1`
- URL: `http://localhost/api/v1/dag-runs/{name}/{dagRunId}/steps/{stepName}/foreach`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
  - none

Lists the items a foreach step expanded to, with the status each item's
body run reached. Items are sorted failed first, then running, then the
rest in index order. Nested foreach items are listed by passing the
parent path a body step reports as foreachParent.

## Path parameters

- `name` string, regex, required: Name of the DAG
- `dagRunId` string, required: Unique identifier for the DAG-run. The special value 'latest' can be used to reference the most recent DAG-run.
- `stepName` string, required

## Query parameters

- `remoteNode` string
- `parent` string
- `status` 'not_started' | 'running' | 'succeeded' | 'failed' | 'aborted': Status of a foreach item's body run
- `page` integer
- `perPage` integer

## Response `200`

A successful response

- ForeachItemList: One page of a foreach step's items
  - `total` integer, required: Number of items the step expanded to, before any status filter
  - `counts` ForeachItemCounts, required: Number of items per body run status
    - `notStarted` integer, required
    - `running` integer, required
    - `succeeded` integer, required
    - `failed` integer, required
    - `aborted` integer, required
  - `items` ForeachItemSummary[], required
    - `item` string, required: Path that addresses the item in the foreach item routes
    - `index` integer, required
    - `key` string, required
    - `status` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9, required: Numeric status code indicating current node state: 0: "Not started" 1: "Running" 2: "Failed" 3: "Aborted" 4: "Success" 5: "Skipped" 6: "Partial Success" 7: "Waiting for manual action" 8: "Rejected" 9: "Retrying"
    - `statusLabel` 'not_started' | 'running' | 'failed' | 'aborted' | 'succeeded' | 'skipped' | 'partially_succeeded' | 'waiting' | 'rejected' | 'retrying', required: Human-readable status description for the node
    - `error` string: Error the body run reported, when it failed
    - `startedAt` string: RFC 3339 timestamp with millisecond precision when the body run started
    - `finishedAt` string: RFC 3339 timestamp with millisecond precision when the body run finished

## Other responses

- `404`: DAG-run or step not found
- `default`: Generic error response

## Changes

> 208 revisions in range; 1 not diffed.

- **2026-10-08** (v1) `9291d665c8f2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dagucloud/apis/dagu/changes/dag-runs/:name/:dagRunId/steps/:stepName/foreach/get.md)

---

[API](https://skmtc.dev/dagucloud/apis/dagu.md) - [All operations](https://skmtc.dev/dagucloud/apis/dagu/llms.txt) - [OpenAPI document](https://skmtc.dev/dagucloud/apis/dagu/revisions/742c8ecb39ce?raw)