--- title: "Retry a failed or stopped run as a new run (session owner only)" method: POST path: "/agents/sessions/{session_id}/runs/{run_id}/retry" tags: ["AI", "Agents"] --- # Retry a failed or stopped run as a new run (session owner only) `POST /agents/sessions/{session_id}/runs/{run_id}/retry` ## Request - Base URL: `https://app.mammoth.io/api/v2` - URL: `https://app.mammoth.io/api/v2/agents/sessions/{session_id}/runs/{run_id}/retry` - Auth: one of: - HTTP bearer - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID` Only the chat's newest run, and only when it failed, was stopped or is stuck running (409 otherwise; a stuck one is stopped first). Starts a new run on the same plan whose task is told what failed and says why, then the failed step runs again and the run goes on. Returns the new run. Refused (403) when called from inside a run's own task (header X-Mammoth-Agent-Run). ## Path parameters - `session_id` string, required - `run_id` integer, required ## Response `200` Request fulfilled, document follows - AgentRunResponse - `run` AgentRunView, required - `id` integer, required - `status` string, required - `step_n` integer, nullable - `steps_total` integer, required - `waiting_reason` string, nullable - `waiting_on` 'approval' | 'question' | 'null', nullable - `active_seconds` integer, required - `cap_seconds` integer, required - `started_at` string, date-time, required - `turn_id` string, nullable - `last_error` string, nullable - `wait_job_id` integer, nullable - `wake_at` string, date-time, nullable - `plan` Plan - `schema_version` 1 - `plan_id` string, required - `revision` integer, required - `kind` 'recommendation' | 'execution', required - `goal` string, required - `steps` PlanStep[], required - `n` integer, required - `title` string, required - `why` string, nullable - `touches` ObjectRef[] - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required - `id` integer, nullable - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet. - `name` string - `project_id` integer, nullable - `project` string - `reads` ObjectRef[] - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required - `id` integer, nullable - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet. - `name` string - `project_id` integer, nullable - `project` string - `makes` string[] - `names` string[] - `renames` Rename[] - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'automation' | 'project', required - `requested` string, required - `final` string, required - `workflow_ops` object[] - `workflow_changes` object[] - `needs` string, nullable - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required - `result` string, nullable - `produced` ObjectRef[] - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required - `id` integer, nullable - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet. - `name` string - `project_id` integer, nullable - `project` string - `changed` ObjectRef[] - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required - `id` integer, nullable - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet. - `name` string - `project_id` integer, nullable - `project` string - `by` 'agent' | 'user' - `after` integer[], nullable - `replaced` boolean - `since_revision` integer, nullable - `wait` StepWait - `job` string, nullable: The id of a job already started, e.g. "4821". - `until` string, date-time, nullable: An ISO 8601 UTC time, e.g. "2026-10-05T03:00:00Z". - `skipped_by` 'user' | 'left_out' | 'null', nullable - `failed_at` string, date-time, nullable - `row_effect` object, nullable - `alert_effect` object, nullable - `join_effect` object, nullable - `send_effect` object, nullable - `credentials` ConnectorCredentialInput - `auth_type` string, required: The connector's authentication scheme, e.g. 'api_key', 'oauth2', 'basic'. Used only to route the submitted values, never rendered as a label. - `fields` CredentialField[], required: The credential fields to collect, in the order they should appear — e.g. [{'name': 'api_key', 'label': 'API key'}]. Name every field the connector actually needs; never include one whose value you already have. Do not include a 'value' — this card never carries one. - `name` string, required - `label` string - `sensitive` boolean - `required` boolean: True when the connector cannot be created without this field, e.g. a username or password. The card marks every other field optional and keeps Connect disabled until each required one is filled. - `credentials_needed` boolean - `supersedes` string, nullable - `request_kind` 'build' | 'automate' | 'fix', nullable - `workflow_id` integer, nullable - `workflow_build` WorkflowBuild - `run_id` string, required - `keys` string[], required - `status` 'running' | 'done' | 'partial' | 'failed' - `message` string, nullable - `built_keys` string[] - `final` object - `run` BuildRun - `id` string, required - `status` string, nullable - `started_at` string, nullable - `finished_at` string, nullable - `steps` BuildRunStep[] - `kind` string, nullable - `label` string, nullable - `keys` string[] - `status` string, nullable - `started_at` string, nullable - `progressed_at` string, nullable - `finished_at` string, nullable - `result` object, nullable - `scope_project` EffectObject - `kind` string, required - `id` integer, nullable - `name` string - `project_id` integer, nullable - `project` string - `worked_after_failure` integer[] - `assumptions` string[] - `combined_effect` object, nullable - `effect` PlanEffect, required: What the plan does, for the plan card (see ``plan_effect``). - `steps` StepEffect[], required - `n` integer, required - `kind` 'read' | 'make' | 'change' | 'deferred', required - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required - `made` EffectObject[], required - `kind` string, required - `id` integer, nullable - `name` string - `project_id` integer, nullable - `project` string - `changed` EffectObject[], required - `kind` string, required - `id` integer, nullable - `name` string - `project_id` integer, nullable - `project` string - `project_id` integer, nullable - `project` string - `makes` object, required - `new_projects` integer, required - `changes` integer, required - `project` string, nullable - `changes_project` string, nullable - `may_change` boolean, required - `may_change_in` string, nullable - `gates` string[] - `gate_target` string - `example` boolean, required: Whether the plan is an example workflow (Show me): a recommendation whose steps carry workflow changes. It is previewed, never built. - `units_total` integer - `units_done` integer - `units_failed` integer - `eta_low_s` integer, nullable - `eta_high_s` integer, nullable ## Other responses - `400`: Bad request syntax or unsupported method - `403`: Request forbidden -- authorization will not help --- [API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/fe078afe239b?raw)