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

# Retrieve one item of a foreach step in a DAG-run

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

## Request

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

Fetches an item's body run: its status and the status of each body step

## 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
- `item` string, required

## Query parameters

- `remoteNode` string

## Response `200`

A successful response

- ForeachItem: One item of a foreach step with the status of each body step
  - `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
  - `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
  - `steps` ForeachBodyStep[], required: Body steps in execution order
    - `name` string, required
    - `id` string
    - `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
    - `startedAt` string: RFC 3339 timestamp with millisecond precision when the body step started
    - `finishedAt` string: RFC 3339 timestamp with millisecond precision when the body step finished
    - `retryCount` integer
    - `hasStdout` boolean, required: Whether a stdout log file was recorded for the step
    - `hasStderr` boolean, required: Whether a stderr log file was recorded for the step
    - `foreachParent` string: For a body step that is itself a foreach, the parent path that lists its items
    - `agentSession` AgentSession: Durable state for a managed coding-agent session
      - `provider` string, required
      - `providerVersion` string
      - `sessionId` string
      - `generation` integer
      - `agent` string
      - `model` string
      - `variant` string
      - `state` 'starting' | 'running' | 'waiting' | 'succeeded' | 'failed' | 'aborted' | 'unavailable', required
      - `lastError` string
      - `usage` AgentUsage
        - `inputTokens` integer
        - `outputTokens` integer
        - `reasoningTokens` integer
        - `totalTokens` integer
        - `cost` number, double
      - `interactions` AgentInteraction[]
        - `id` string, required
        - `kind` 'permission' | 'question', required
        - `status` 'pending' | 'answered' | 'rejected', required
        - `permission` string
        - `patterns` string[]
        - `allowForSessionPatterns` string[]
        - `questions` AgentQuestion[]
          - `header` string, required
          - `question` string, required
          - `options` AgentQuestionOption[]
            - `label` string, required
            - `description` string
          - `multiple` boolean
          - `custom` boolean
        - `decision` string
        - `answers` array[]
          - string[]
        - `createdAt` string
        - `expiresAt` string: RFC 3339 time after which an answer fails the step. Set for browser asks.
        - `respondedAt` string
        - `respondedBy` string
        - `respondedById` string
      - `events` AgentSessionEvent[]
        - `sequence` integer, required
        - `id` string, required
        - `type` string, required
        - `timestamp` string
        - `role` string
        - `content` string
        - `name` string
        - `status` string
        - `files` string[]
        - `position` integer: The operation's place in the step's list, from 1; absent for an event that is not one operation
        - `via` string: How an operation ran: screen for a replayed recording, model for a model request; absent for one that decides nothing
        - `durationMs` integer: How long the operation took, in milliseconds; absent when under one
        - `tokens` integer: Model tokens the operation used; absent when none
    - `modelUsage` StepModelUsage: What a step's calls to models used, over every attempt of the step in its run
      - `models` ModelUsage[]: Usage of each model: the step's own calls and what the tools it ran, such as a coding agent, reported
        - `provider` string, required: Provider of the model, such as openai or openrouter
        - `model` string, required: Model the calls named
        - `calls` integer, required: Number of calls
        - `inputTokens` integer: Prompt tokens, cached and cache-write tokens included
        - `cachedInputTokens` integer: Prompt tokens read from the provider's prompt cache
        - `cacheWriteTokens` integer: Prompt tokens written to the provider's prompt cache
        - `outputTokens` integer: Completion tokens, reasoning tokens included
        - `reasoningTokens` integer: Completion tokens spent on reasoning
        - `cost` number, double: Cost in US dollars the provider reported for costReportedCalls of the calls
        - `costReportedCalls` integer: Number of calls whose cost the provider reported; cost is whole only when it equals calls
      - `notReported` string: A tool the step ran whose model usage could not be read, such as a coding agent's command line

## Other responses

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

## Changes

> 208 revisions in range; 1 not diffed.

- **2026-10-27** (v1) `2423ce6c5598`: 2 info
  - added the optional property `steps/items/agentSession` to the response with the `200` status
  - added the optional property `steps/items/modelUsage` to the response with the `200` status
- **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/:item/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)