# agent_run_list

List Agent Runs

## Beschreibung

Lists `AgentRun` rows the caller can see, newest first.
Scoped via `AgentRunPolicy::Scope` — members see only
runs from their own schedules; admins and employers see
every run in the account.

Filters (all optional):
- `agent_schedule_id` / `agent_id` —
  narrow by the linked record (prefix IDs)
- `status` — "queued" / "running" / "success" / "failed"
  / "completed_with_errors" (ran but a tool/action errored)
  / "skipped"
- `created_at` — return only rows created at or after
  this moment. Accepts: ISO 8601, `YYYY-MM-DD`,
  space-separated, Unix epoch, or a relative offset
  like `+30m` / `+2h` / `+1d` / `+1w` (which means "in
  the future from now" — useful as a sentinel, less so
  for run-listing).
- `limit` — default 50, max 250

Each row carries a `url` field pointing at the run's
page so a UI can link straight to it.

## Zugriff

Zugriffsprofil: `gated`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja |  |
| `agent_schedule_id` | string | Nein |  |
| `agent_id` | string | Nein |  |
| `status` | string | Nein |  |
| `created_at` | string | Nein | Lower bound. Accepts: ISO 8601 ('2026-05-07T10:00:00Z'), date-only ('2026-05-07'), space-separated ('2026-05-07 10:00'), Unix epoch seconds ('1746604800'), or relative offset ('+30m', '+2h', '+1d', '+1w') |
| `limit` | integer | Nein |  |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string"
    },
    "agent_schedule_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "success",
        "failed",
        "skipped"
      ]
    },
    "created_at": {
      "type": "string",
      "description": "Lower bound. Accepts: ISO 8601 ('2026-05-07T10:00:00Z'), date-only ('2026-05-07'), space-separated ('2026-05-07 10:00'), Unix epoch seconds ('1746604800'), or relative offset ('+30m', '+2h', '+1d', '+1w')"
    },
    "limit": {
      "type": "integer",
      "default": 50
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "agent_runs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "agent_schedule_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "agent_trigger_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "agent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "scheduled_for": {
            "type": [
              "string",
              "null"
            ]
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "skip_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "created_at",
          "url"
        ]
      }
    }
  },
  "required": [
    "agent_runs"
  ],
  "type": "object"
}
```