Get automation status

The exact operation and all referenced components, including recursive schemas.

{
  "operation": {
    "operationId": "automations.status",
    "summary": "Get automation status",
    "tags": [
      "automations"
    ],
    "description": "The bounded, model-readable state of one automation: its lifecycle, its overall monitoring status, its most recent evaluation and occurrence. Unlike `automations.get`, evidence here is fixed-size and reviewed for a conversation, never the raw stored value.",
    "parameters": [
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "userId",
        "required": true,
        "description": "The user in the path; must equal the token's own account."
      },
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "automationId",
        "required": true,
        "description": "The automation's id."
      }
    ],
    "security": [
      {
        "apiKey": [],
        "userToken": []
      }
    ],
    "responses": {
      "200": {
        "description": "The automation's current state and observations.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "asOf": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
                  "description": "The database snapshot time this status was read as of."
                },
                "automationId": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "The automation's id."
                },
                "name": {
                  "type": "string",
                  "maxLength": 120,
                  "description": "The automation's name."
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "enabled",
                    "paused",
                    "archived"
                  ],
                  "description": "The automation's lifecycle: `enabled` and firing, `paused` and not firing, or `archived` for good."
                },
                "monitoring": {
                  "type": "string",
                  "enum": [
                    "waiting",
                    "healthy",
                    "stale",
                    "unavailable",
                    "paused",
                    "completed"
                  ],
                  "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent."
                },
                "behavior": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string",
                      "maxLength": 320,
                      "description": "The excerpt's text, cut to fit if the source was longer."
                    },
                    "truncated": {
                      "type": "boolean",
                      "description": "Whether the source text was longer than `text` and had to be cut."
                    }
                  },
                  "required": [
                    "text",
                    "truncated"
                  ],
                  "description": "A plain-language rendering of the rule's schedule, condition and firing policy — the same text `automations.search` matches words against."
                },
                "lastCheck": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "at": {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
                          "description": "When this check last ran."
                        },
                        "condition": {
                          "type": "string",
                          "enum": [
                            "matched",
                            "not_matched",
                            "unknown"
                          ],
                          "description": "Whether the rule's condition held at this check: `matched`, `not_matched`, or `unknown` when a needed source was unavailable."
                        },
                        "facts": {
                          "maxItems": 3,
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "label": {
                                "type": "string",
                                "maxLength": 80,
                                "description": "What this recorded fact measures."
                              },
                              "value": {
                                "type": "string",
                                "maxLength": 160,
                                "description": "The fact's value, as text."
                              },
                              "unit": {
                                "description": "The value's unit, when it has one.",
                                "type": "string",
                                "maxLength": 40
                              },
                              "observedAt": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "date-time",
                                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "When the underlying observation was made, or null when unknown."
                              }
                            },
                            "required": [
                              "label",
                              "value",
                              "observedAt"
                            ]
                          },
                          "description": "Up to three facts behind this check's verdict."
                        },
                        "omittedFacts": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991,
                          "description": "How many additional facts this check recorded but the response left out."
                        }
                      },
                      "required": [
                        "at",
                        "condition",
                        "facts",
                        "omittedFacts"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The automation's most recent evaluation, or null before the first."
                },
                "issue": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "text": {
                          "type": "string",
                          "maxLength": 240,
                          "description": "The excerpt's text, cut to fit if the source was longer."
                        },
                        "truncated": {
                          "type": "boolean",
                          "description": "Whether the source text was longer than `text` and had to be cut."
                        }
                      },
                      "required": [
                        "text",
                        "truncated"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "A plain-language reason monitoring is not healthy right now — an operator hold, a paused or archived automation, an unavailable or stale source, or nothing evaluated yet — or null when nothing is wrong."
                },
                "latestOccurrence": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "at": {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
                          "description": "When this occurrence was recorded."
                        },
                        "delivery": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "deferred",
                            "accepted",
                            "rejected",
                            "canceled",
                            "skipped",
                            "coalesced"
                          ],
                          "description": "This occurrence's delivery state: `pending` waiting to run, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to a run, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before running, `skipped` a previous occurrence was still active, `coalesced` merged into a newer match."
                        },
                        "reason": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "text": {
                                  "type": "string",
                                  "maxLength": 240,
                                  "description": "The excerpt's text, cut to fit if the source was longer."
                                },
                                "truncated": {
                                  "type": "boolean",
                                  "description": "Whether the source text was longer than `text` and had to be cut."
                                }
                              },
                              "required": [
                                "text",
                                "truncated"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Why the occurrence is in this state, or null when there is none to give."
                        },
                        "runId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid",
                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                              "description": "The stable public agent run id, retained across approval continuations."
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The occurrence's stable agent run, when one has started; else null."
                        }
                      },
                      "required": [
                        "at",
                        "delivery",
                        "reason",
                        "runId"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The automation's most recently recorded occurrence, or null before its first."
                }
              },
              "required": [
                "asOf",
                "automationId",
                "name",
                "state",
                "monitoring",
                "behavior",
                "lastCheck",
                "issue",
                "latestOccurrence"
              ]
            }
          }
        }
      },
      "400": {
        "$ref": "#/components/responses/InvalidInput"
      },
      "401": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "403": {
        "$ref": "#/components/responses/Forbidden"
      },
      "404": {
        "$ref": "#/components/responses/NotFound"
      },
      "412": {
        "$ref": "#/components/responses/AccountNotProvisioned"
      },
      "429": {
        "$ref": "#/components/responses/TooManyRequests"
      },
      "500": {
        "$ref": "#/components/responses/Internal"
      },
      "503": {
        "$ref": "#/components/responses/Unavailable"
      }
    }
  },
  "components": {
    "responses": {
      "InvalidInput": {
        "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "AccountNotProvisioned": {
        "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Internal": {
        "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The kind of problem as a URN, `urn:fin:error:<kind>`; stable, compare against it"
          },
          "title": {
            "type": "string",
            "description": "The kind's human title, for logs; never parse it"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "The HTTP status, repeated in the body"
          },
          "reason": {
            "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted",
            "type": "string",
            "enum": [
              "run_active",
              "budget_exhausted",
              "approval_not_pending",
              "execution_capacity",
              "execution_unavailable",
              "stop_pending",
              "automation_changed",
              "automation_held",
              "automation_invalid",
              "automation_completed",
              "automation_limit",
              "profile_unknown_tool",
              "deployment_paused",
              "run_not_active",
              "withdrawal_changed",
              "credential_expired",
              "account_disabled",
              "account_not_provisioned",
              "provider_unavailable",
              "engine_unavailable",
              "invalid_input",
              "internal",
              "partner_key_required",
              "partner_key_invalid",
              "subject_mismatch",
              "origin_rejected",
              "permission_required",
              "rate_limited",
              "stream_capacity",
              "invalid_cursor"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "The id Fin used for this request; quote it when reporting a problem"
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether repeating the same request later can succeed without changing it"
          },
          "detail": {
            "description": "Only on `invalid_input`: which part of the request failed validation",
            "type": "string"
          },
          "issues": {
            "description": "Only on `invalid_input`: one entry per failing field",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string",
                  "description": "The JSON pointer of the failing field; empty for the root object"
                },
                "message": {
                  "type": "string",
                  "description": "Why the field failed"
                }
              },
              "required": [
                "path",
                "message"
              ]
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "requestId",
          "retryable"
        ],
        "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack."
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "userToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}