<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/api/agent/get-agent-decisions

  Any page on this site is available as raw markdown by appending .md to its URL.
-->


# What the agent decided NOT to protect, across every sweep

`GET /agent/decisions`

**Required scope:** `documents:read`

decisions[] otherwise lives inside a single run, so this is the route for "what did my agent leave alone last month, and why". Consent-gated: read meta.consent before reporting an empty list as a clean sweep.

Read decisions. Requires scope documents:read.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `decision` | query | no | one of the 11 decision codes; an unknown code returns 400 rather than an empty list |
| `docType` | query | no | filter by doc type |
| `docState` | query | no | filter by doc state |
| `workspace` | query | no | workspace id |
| `objective` | query | no | the objective the sweep served |
| `from` | query | no | ISO 8601, filters on the sweep finish time |
| `to` | query | no | ISO 8601, filters on the sweep finish time |
| `search` | query | no | matches the file path and the reason |
| `page` | query | no | default 1 |
| `limit` | query | no | default 50, max 100 |

## Responses

| Status | Meaning |
|---|---|
| `200` | Success Returns: per row: path, decision, reason, docType, docState, servesObjective, confidence, folderConfidence, plus runId and sweptAt (when that sweep finished). meta.consent is reported | partial | never_consented | no_runs: an EMPTY list is not the same as "nothing was excluded", because decisions are consent-gated and a customer may never have opted in. meta.truncatedRuns counts runs that hit the 500-decision cap. |
| `400` | BadRequest |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | RateLimited |

## Example

```bash
curl -X GET "https://backend.immut.io/api/v1/agent/decisions" \
  -H "Authorization: Bearer $IMMUT_API_KEY"
```

## OpenAPI fragment

```json
{
  "/agent/decisions": {
    "get": {
      "operationId": "getagentdecisions",
      "summary": "What the agent decided NOT to protect, across every sweep. decisions[] otherwise lives inside a single run, so this is the route for \"what did my agent leave alone last month, and why\". Consent-gated: read meta.consent before reporting an empty list as a clean sweep.",
      "description": "Read decisions. Requires scope documents:read.",
      "parameters": [
        {
          "name": "decision",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "one of the 11 decision codes; an unknown code returns 400 rather than an empty list"
        },
        {
          "name": "docType",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "filter by doc type"
        },
        {
          "name": "docState",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "filter by doc state"
        },
        {
          "name": "workspace",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "workspace id"
        },
        {
          "name": "objective",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "the objective the sweep served"
        },
        {
          "name": "from",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "ISO 8601, filters on the sweep finish time"
        },
        {
          "name": "to",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "ISO 8601, filters on the sweep finish time"
        },
        {
          "name": "search",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "matches the file path and the reason"
        },
        {
          "name": "page",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 1"
        },
        {
          "name": "limit",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 50, max 100"
        }
      ],
      "responses": {
        "200": {
          "description": "Success Returns: per row: path, decision, reason, docType, docState, servesObjective, confidence, folderConfidence, plus runId and sweptAt (when that sweep finished). meta.consent is reported | partial | never_consented | no_runs: an EMPTY list is not the same as \"nothing was excluded\", because decisions are consent-gated and a customer may never have opted in. meta.truncatedRuns counts runs that hit the 500-decision cap."
        },
        "400": {
          "$ref": "#/components/responses/BadRequest"
        },
        "401": {
          "$ref": "#/components/responses/Unauthorized"
        },
        "403": {
          "$ref": "#/components/responses/Forbidden"
        },
        "429": {
          "$ref": "#/components/responses/RateLimited"
        }
      },
      "tags": [
        "Agent"
      ],
      "x-required-scope": "documents:read"
    }
  }
}
```