---
title: Automation run inspector
url: /docs/developers/reference/automation-run-inspector
---

# Automation run inspector

`automation.run-inspector@1`

Shows one run of an automation: where it is, what each step did, what it produced and what went wrong. It reads and changes nothing. It needs a key with **Read automations**.

## Look at a run

Replace `YOUR_FEATURE_ID` with the `featureId` this operation's catalogue entry gives, and `YOUR_RUN_REF` with a run's `runRef` from [Find automation runs](automation-runs.md).

```curl tabs
# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "runInspector",
    "contractRef": "automation.run-inspector@1"
  },
  "operationId": "inspect-run-1",
  "input": {
    "runRef": "YOUR_RUN_REF"
  }
}'
```

```javascript tabs
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "runInspector",
        "contractRef": "automation.run-inspector@1"
      },
      "operationId": "inspect-run-1",
      "input": {
        "runRef": "YOUR_RUN_REF"
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);
```

```python tabs
import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "runInspector",
            "contractRef": "automation.run-inspector@1",
        },
        "operationId": "inspect-run-1",
        "input": {
            "runRef": "YOUR_RUN_REF",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## Parameters

What goes in `input`:

| Name | Type | Required | Description |
|---|---|---|---|
| `runRef` | string | Yes | The run to show: its `runRef` from [Find automation runs](automation-runs.md). |

## Response

A call that worked answers `200` with an `applied` receipt; its `output` holds these fields, among others. `GET /catalog/automation.run-inspector@1` answers the complete shape as JSON Schema.

| Name | Type | Description |
|---|---|---|
| `runRef` | string | The run's reference. |
| `revision` | integer | The run's revision. Send it as `expectedRevision` to [Suspend](automation-run-suspend.md), [Resume](automation-run-resume.md) or [Cancel](automation-run-cancel.md) so a change you did not see is never overridden. |
| `featureId` | string | The feature the run belongs to. |
| `source` | object | The automation or built-in setup the run follows. |
| `source.kind` | one of `preset`, `workflow` | `preset` for a built-in setup, `workflow` for an automation of your own. |
| `source.ref` | string | Its reference. |
| `state` | one of `preparing`, `queued`, `running`, `waiting`, `needs-input`, `suspended`, `succeeded`, `completed-with-errors`, `failed`, `uncertain`, `cancelled` | Where the run is: `preparing`, `queued`, `running`, `waiting`, `needs-input`, `suspended`, `succeeded`, `completed-with-errors`, `failed`, `uncertain` or `cancelled`. |
| `parentRunRef` | null or string | The run that started this one, or `null`. |
| `output` | any JSON value | What the run produced so far; its shape depends on the automation. |
| `diagnostics` | array of object | Problems the run met, each with a `code`, the `path` it is about and a `message`. |
| `nodes` | array of object | The run's steps, in order. |
| `nodes[].id` | string | The step's name in the automation. |
| `nodes[].state` | one of `ready`, `running`, `waiting`, `succeeded`, `failed`, `uncertain`, `cancelled` | `ready`, `running`, `waiting`, `succeeded`, `failed`, `uncertain` or `cancelled`. |
| `nodes[].generation` | integer | How many times the step has been started afresh (a step that repeats counts up). |
| `nodes[].operationId` | null or string | The `operationId` of the call the step made, or `null`. |
| `nodes[].receipt` | null or object | The receipt that call answered, or `null`. |
| `nodes[].items` | array of object | For a step that handles a list, each item and where it is. |
| `nodes[].waiting` | object | Present while the step waits: for an event (`await`), a time (`wait`) or a choice (`exit`). |
| `nodes[].waiting.deadline` | string (date-time) | When the wait ends on its own. |

```json title="Response"
{
  "status": "applied",
  "operationId": "inspect-run-1",
  "output": {
    "runRef": "11111111-2222-4333-8444-555555555555",
    "revision": 3,
    "businessProfileId": "YOUR_BUSINESS_ID",
    "featureId": "juniper-cakes.automations",
    "source": {
      "kind": "workflow",
      "ref": "YOUR_AUTOMATION_REF"
    },
    "state": "succeeded",
    "parentRunRef": null,
    "output": {},
    "diagnostics": [],
    "nodes": [
      {
        "id": "send-thanks",
        "state": "succeeded",
        "generation": 1,
        "operationId": "send-thanks-1",
        "receipt": null
      }
    ]
  }
}
```

## Errors

It reads and changes nothing. Besides the answers every request can get ([Errors](../errors.md)), its receipt can say:

| Status | HTTP | What it means |
|---|---|---|
| `rejected` | 400, or 403 when it's a matter of access | Not done. `diagnostics` says why: each has a `code`, a `path` into what you sent and a `message`. |

The codes in `diagnostics` you're most likely to see:

| Code | Status | What it means |
|---|---|---|
| `AUTOMATION.RUN_NOT_FOUND` | `rejected` | No such run here for this key. |
| `AUTOMATION.RUN_MOVED` | `conflict` | The run changed while it was being read. Read it again. |
| `AUTOMATION.GRAPH_NOT_EXECUTABLE` | `rejected` | The automation this run follows can no longer be read, so the run cannot be shown. |