> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations: jobs

> Long work and waiting for your approval: read, wait for, list and cancel jobs. For each operation: what it does, whether it asks you first, its inputs and an example call.

Long work and waiting for your approval: read, wait for, list and cancel jobs. 4 operations. How to call them, and what the answers mean: [Operations reference](https://docs.summerengine.com/mcp/operations.md).

> [!NOTE]
>
> Generated from the `summer-engine` npm package `4.8.0`: its public operation catalog (`registry/operations/public-catalog.json`) and its engine and local operations. If something here is wrong, the operation's definition is wrong.

| Operation | What it does | Asks you first |
| - | - | - |
| [`jobs.cancel`](#cancel) | Stop one of the person's jobs that has not finished: a plan agent request, a cloud build, or a publish request still waiting for the owner (its link stops working). | Not by default |
| [`jobs.get`](#get) | Read one job once: its state (queued, running, awaiting\_approval, done, failed...), progress and, when done, its result. | Never |
| [`jobs.list`](#list) | List the person's jobs, newest first: with planId, a plan's agent requests and cloud builds; with gameId, its store uploads and publish requests; with neither, their asset generations of the last 48 hours and the store… | Never |
| [`jobs.wait`](#wait) | Wait up to timeoutSeconds (at most 50) for a job to finish, then return it. | Never |

***

### cancel

`jobs.cancel`: **Cancel a job**

Stop one of the person's jobs that has not finished: a plan agent request, a cloud build, or a publish request still waiting for the owner (its link stops working). Work already saved stays. Returns the job. Next: jobs.list.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "jobs.cancel"` |
| **CLI** | `summer jobs cancel` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |
| **3.x names** | `summer_board_agent_cancel`, `summer_board_build_cancel` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "jobId": {
>       "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 260
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "jobId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "job": {
>       "type": "object",
>       "properties": {
>         "id": {
>           "type": "string"
>         },
>         "kind": {
>           "type": "string"
>         },
>         "state": {
>           "type": "string",
>           "enum": [
>             "queued",
>             "running",
>             "awaiting_approval",
>             "done",
>             "failed",
>             "cancelled",
>             "declined",
>             "expired",
>             "stale"
>           ]
>         },
>         "progress": {
>           "type": "number"
>         },
>         "result": {
>           "description": "The finished work: asset ids and URLs, or the approved change.",
>           "type": "object",
>           "additionalProperties": {}
>         },
>         "error": {
>           "type": "object",
>           "properties": {
>             "code": {
>               "type": "string"
>             },
>             "message": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "code",
>             "message"
>           ],
>           "additionalProperties": false
>         },
>         "message": {
>           "type": "string"
>         },
>         "pollAfterSeconds": {
>           "type": "number"
>         },
>         "model": {
>           "description": "Summer API jobs: the model id it runs.",
>           "type": "string"
>         },
>         "estimatedPrice": {
>           "description": "Summer API jobs: the price quoted when it was accepted, in USD.",
>           "type": "string"
>         },
>         "price": {
>           "description": "Summer API jobs: what it charged, in USD, once known.",
>           "type": "string"
>         }
>       },
>       "required": [
>         "id",
>         "kind",
>         "state"
>       ],
>       "additionalProperties": false
>     }
>   },
>   "required": [
>     "job"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Take back a publish request before the owner answers.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "jobs.cancel",
    "input": {
      "jobId": "apr:g_123:goa_01J"
    }
  }
}
```

```bash CLI theme={null}
summer jobs cancel --job-id apr:g_123:goa_01J
```

***

### get

`jobs.get`: **Check a job**

Read one job once: its state (queued, running, awaiting\_approval, done, failed...), progress and, when done, its result. Next: jobs.wait to wait for it.

| | |
| - | - |
| **MCP** | `summer_jobs_get`, a tool on the hosted MCP and the npm assets profile. Elsewhere: `summer_call` with `"op": "jobs.get"` |
| **CLI** | `summer jobs get` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_check_job`, `summer_board_agent_task`, `summer_board_build_status` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "jobId": {
>       "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 260
>     }
>   },
>   "required": [
>     "jobId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "job": {
>       "type": "object",
>       "properties": {
>         "id": {
>           "type": "string"
>         },
>         "kind": {
>           "type": "string"
>         },
>         "state": {
>           "type": "string",
>           "enum": [
>             "queued",
>             "running",
>             "awaiting_approval",
>             "done",
>             "failed",
>             "cancelled",
>             "declined",
>             "expired",
>             "stale"
>           ]
>         },
>         "progress": {
>           "type": "number"
>         },
>         "result": {
>           "description": "The finished work: asset ids and URLs, or the approved change.",
>           "type": "object",
>           "additionalProperties": {}
>         },
>         "error": {
>           "type": "object",
>           "properties": {
>             "code": {
>               "type": "string"
>             },
>             "message": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "code",
>             "message"
>           ],
>           "additionalProperties": false
>         },
>         "message": {
>           "type": "string"
>         },
>         "pollAfterSeconds": {
>           "type": "number"
>         },
>         "model": {
>           "description": "Summer API jobs: the model id it runs.",
>           "type": "string"
>         },
>         "estimatedPrice": {
>           "description": "Summer API jobs: the price quoted when it was accepted, in USD.",
>           "type": "string"
>         },
>         "price": {
>           "description": "Summer API jobs: what it charged, in USD, once known.",
>           "type": "string"
>         }
>       },
>       "required": [
>         "id",
>         "kind",
>         "state"
>       ],
>       "additionalProperties": false
>     }
>   },
>   "required": [
>     "job"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Is the 3D model done?

```json MCP theme={null}
{
  "name": "summer_jobs_get",
  "arguments": {
    "jobId": "gen:4821"
  }
}
```

```bash CLI theme={null}
summer jobs get --job-id gen:4821
```

***

### list

`jobs.list`: **List my jobs**

List the person's jobs, newest first: with planId, a plan's agent requests and cloud builds; with gameId, its store uploads and publish requests; with neither, their asset generations of the last 48 hours and the store jobs of the five games changed last. Next: jobs.wait or jobs.cancel.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "jobs.list"` |
| **CLI** | `summer jobs list` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_board_agent_tasks` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `gameId` | string | No | One game (from games.list); else the five games changed last. |
| `planId` | string | No | One plan (from plans.list): its agent requests and cloud builds. |
| `kind` | "gen" \| "upload" \| "apr" \| "plan" \| "build" | No | gen: asset generations (no gameId or planId); upload: store uploads; apr: publish requests; plan: plan agent requests; build: cloud builds (plan and build need planId). |
| `state` | "queued" \| "running" \| "awaiting\_approval" \| "done" \| "failed" \| "cancelled" \| "declined" \| "expired" \| "stale" | No | |
| `limit` | integer | No | Default `10`. Range 1 to 50. |
| `cursor` | string | No | nextCursor from the previous page. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "gameId": {
>       "description": "One game (from games.list); else the five games changed last.",
>       "type": "string",
>       "pattern": "^[A-Za-z0-9_-]{1,128}$"
>     },
>     "planId": {
>       "description": "One plan (from plans.list): its agent requests and cloud builds.",
>       "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)$"
>     },
>     "kind": {
>       "description": "gen: asset generations (no gameId or planId); upload: store uploads; apr: publish requests; plan: plan agent requests; build: cloud builds (plan and build need planId).",
>       "type": "string",
>       "enum": [
>         "gen",
>         "upload",
>         "apr",
>         "plan",
>         "build"
>       ]
>     },
>     "state": {
>       "type": "string",
>       "enum": [
>         "queued",
>         "running",
>         "awaiting_approval",
>         "done",
>         "failed",
>         "cancelled",
>         "declined",
>         "expired",
>         "stale"
>       ]
>     },
>     "limit": {
>       "default": 10,
>       "type": "integer",
>       "minimum": 1,
>       "maximum": 50
>     },
>     "cursor": {
>       "description": "nextCursor from the previous page.",
>       "type": "string",
>       "pattern": "^\\d{1,3}$"
>     }
>   }
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "items": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "properties": {
>           "jobId": {
>             "type": "string"
>           },
>           "kind": {
>             "type": "string",
>             "enum": [
>               "gen",
>               "upload",
>               "apr",
>               "plan",
>               "build"
>             ]
>           },
>           "op": {
>             "description": "The op that started it.",
>             "type": "string"
>           },
>           "state": {
>             "type": "string",
>             "enum": [
>               "queued",
>               "running",
>               "awaiting_approval",
>               "done",
>               "failed",
>               "cancelled",
>               "declined",
>               "expired",
>               "stale"
>             ]
>           },
>           "gameId": {
>             "type": "string"
>           },
>           "planId": {
>             "type": "string"
>           },
>           "what": {
>             "description": "The generation, the upload, the publish request, the plan agent request or the build, in a few words.",
>             "type": "string"
>           },
>           "createdAt": {
>             "anyOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           }
>         },
>         "required": [
>           "jobId",
>           "kind",
>           "op",
>           "state",
>           "what",
>           "createdAt"
>         ],
>         "additionalProperties": false
>       }
>     },
>     "nextCursor": {
>       "anyOf": [
>         {
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     }
>   },
>   "required": [
>     "items",
>     "nextCursor"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Which uploads of this game is Summer still checking?

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "jobs.list",
    "input": {
      "gameId": "g_123",
      "state": "running"
    }
  }
}
```

```bash CLI theme={null}
summer jobs list --game-id g_123 --state running
```

***

### wait

`jobs.wait`: **Wait for a job**

Wait up to timeoutSeconds (at most 50) for a job to finish, then return it. If it is still not done, call again. Approvals wait for the person.

| | |
| - | - |
| **MCP** | `summer_jobs_wait`, a tool on the hosted MCP and the npm assets profile. Elsewhere: `summer_call` with `"op": "jobs.wait"` |
| **CLI** | `summer jobs wait` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |
| `timeoutSeconds` | integer | No | Most seconds to wait in this call (1 to 50). Default `25`. Range 1 to 50. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "jobId": {
>       "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 260
>     },
>     "timeoutSeconds": {
>       "description": "Most seconds to wait in this call (1 to 50).",
>       "default": 25,
>       "type": "integer",
>       "minimum": 1,
>       "maximum": 50
>     }
>   },
>   "required": [
>     "jobId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "job": {
>       "type": "object",
>       "properties": {
>         "id": {
>           "type": "string"
>         },
>         "kind": {
>           "type": "string"
>         },
>         "state": {
>           "type": "string",
>           "enum": [
>             "queued",
>             "running",
>             "awaiting_approval",
>             "done",
>             "failed",
>             "cancelled",
>             "declined",
>             "expired",
>             "stale"
>           ]
>         },
>         "progress": {
>           "type": "number"
>         },
>         "result": {
>           "description": "The finished work: asset ids and URLs, or the approved change.",
>           "type": "object",
>           "additionalProperties": {}
>         },
>         "error": {
>           "type": "object",
>           "properties": {
>             "code": {
>               "type": "string"
>             },
>             "message": {
>               "type": "string"
>             }
>           },
>           "required": [
>             "code",
>             "message"
>           ],
>           "additionalProperties": false
>         },
>         "message": {
>           "type": "string"
>         },
>         "pollAfterSeconds": {
>           "type": "number"
>         },
>         "model": {
>           "description": "Summer API jobs: the model id it runs.",
>           "type": "string"
>         },
>         "estimatedPrice": {
>           "description": "Summer API jobs: the price quoted when it was accepted, in USD.",
>           "type": "string"
>         },
>         "price": {
>           "description": "Summer API jobs: what it charged, in USD, once known.",
>           "type": "string"
>         }
>       },
>       "required": [
>         "id",
>         "kind",
>         "state"
>       ],
>       "additionalProperties": false
>     },
>     "finished": {
>       "type": "boolean"
>     },
>     "waitedSeconds": {
>       "type": "number"
>     }
>   },
>   "required": [
>     "job",
>     "finished",
>     "waitedSeconds"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Wait for a 3D job.

```json MCP theme={null}
{
  "name": "summer_jobs_wait",
  "arguments": {
    "jobId": "gen:4821",
    "timeoutSeconds": 30
  }
}
```

```bash CLI theme={null}
summer jobs wait --job-id gen:4821 --timeout-seconds 30
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.