---
title: Tasks
description: Hand a piece of work to a cloud agent and get the result back, from the CLI, the MCP server, or the API.
---
<PreviewBanner>Breaking changes may occur.</PreviewBanner>

A task is one request to a [cloud agent](/cloud-agents) and its result. You describe the work, Railway runs it on an agent, and you read the outcome when it finishes. You don't connect to the agent or keep a session open.

Use tasks to hand off work from a script, an editor, or another system: fix a failing test and open a pull request, investigate an error, or summarize what changed in an environment.

## How tasks work

Railway tracks each task from dispatch to result, so a task survives a closed terminal or a dropped connection.

1. You dispatch a task with a prompt and a target environment.
2. Railway creates a cloud agent, or wakes the one you named, and sends it the prompt.
3. The agent works in the background. You can come back for the result, follow progress live, or receive webhooks.
4. The task ends with a result, a failure, or a cancellation.

A task has one of these statuses:

| Status | Meaning |
|--------|---------|
| `PENDING` | Accepted. The agent is being prepared. |
| `RUNNING` | The agent is working. |
| `AWAITING_INPUT` | The agent asked a question or needs an approval. |
| `COMPLETED` | Finished. The result is available. |
| `FAILED` | Ended with an error. |
| `CANCELLED` | Stopped by a cancel request. |

A finished task keeps its result, so you can read it after the agent sleeps or is deleted.

## Where a task runs

Every task runs on a cloud agent in the environment you choose. What you pass decides which one.

| You pass | The task runs on |
|----------|------------------|
| Nothing | A new cloud agent |
| An agent | That agent, in a fresh session |
| An earlier task | The same agent and session as that task |
| A conversation key | The agent and session that key started, or a new agent on first use |

A fresh session has no memory of earlier tasks on the same agent. To continue earlier work, reply to its task or reuse its conversation key.

A conversation key is a name you choose, such as `linear:ENG-123`. The first task with a key starts an agent. Later tasks with the same key continue it, each waiting for the one before to finish.

## Billing

Starting a new cloud agent creates a virtual machine. The machine is billed while it's active and sleeps after five minutes idle. The model usage of a task is billed as [Railway Agent usage](/pricing#railway-agent).

Because a new agent costs money, the CLI and the MCP server tell you before a task starts one. See the notice behavior for [`railway ca task`](/cli/ca#billing-notice) and [`railway agent`](/cli/agent#billing-notice).

## Run a task from the CLI

`railway ca task` dispatches tasks and reads their results. `run` hands the task to Railway and returns the task ID. The task runs in the background.

```bash
railway ca task run "Fix the failing test in api/ and open a pull request" \
  --repo acme/api
```

Pick up the result when you're ready:

```bash
railway ca task status <task-id>
```

To follow a task live, add `--watch`. Use it on `run` to follow the task you're dispatching, or on `status` to follow one that is already running.

```bash
railway ca task run "Summarize yesterday's errors" --watch
railway ca task status <task-id> --watch
```

While watching, the CLI prints each tool the agent uses, then the result. A watch ends when the task completes, fails, is cancelled, or stops to ask for an answer.

Press Ctrl-C to stop watching. The task keeps running, and the CLI prints the command to return to it. See [Watch a task](/cli/ca#watch-a-task) for the details.

Continue the same work with a follow-up:

```bash
railway ca task run "Add a changelog entry for that fix" --reply-to <task-id>
```

See the [`railway ca task` reference](/cli/ca#tasks) for every command and flag.

## Ask questions with the Railway Agent

[`railway agent`](/cli/agent) is a conversational front end to tasks. Each message is a task, and every thread in an environment shares one cloud agent named `railway-agent`.

```bash
railway agent -p "why is my backend service failing to deploy?"
```

## Run a task from an AI assistant

The [Railway MCP server](/ai/mcp-server) exposes tasks as tools, so an assistant in your editor can hand work to a cloud agent.

| Tool | Purpose |
|------|---------|
| `run-cloud-agent-task` | Dispatch a task. Asks you to confirm before starting a new agent. |
| `check-cloud-agent-task` | Read a task's status and result |
| `respond-cloud-agent-task` | Answer a question or approval |
| `cancel-cloud-agent-task` | Cancel a running task |
| `list-cloud-agent-tasks` | List tasks in an environment |
| `list-cloud-agent-models` | List the models a task can run on |
| `get-cloud-agent-transcript` | Read what the agent did during a session |

## Answer the agent

An agent can stop to ask a question or request an approval. The task moves to `AWAITING_INPUT` until you answer.

Questions are off unless you turn them on. Pass `--interactive` to `railway ca task run`, or set `interactive: true` in the API, to let the agent ask. With `interactive: false`, the agent decides on its own or gives up with a reason.

A task running in the background stays in `AWAITING_INPUT` until you come back to it. `railway ca task status` prints what the agent asked, and a watch ends at that point.

To answer a question, send your answer to the same agent and session. Railway delivers it as the answer instead of starting a new turn.

```bash
railway ca task run "Use the staging database" --reply-to <task-id>
```

To answer an approval, use `respond`:

```bash
railway ca task respond <task-id> allow
```

## Use the API

The [public API](/integrations/api) exposes every task operation, so your own services can dispatch tasks and act on their results. Dispatch a task with `cloudAgentTaskDispatch`:

```graphql
mutation {
  cloudAgentTaskDispatch(
    input: {
      projectId: "<project-id>"
      environmentId: "<environment-id>"
      prompt: "Fix the failing test in api/ and open a pull request"
      source: { repo: "acme/api" }
    }
  ) {
    taskId
    cloudAgentId
    sessionId
    status
  }
}
```

The dispatch returns at once. Read the result with `cloudAgentTask`, or have Railway call a webhook when the task changes state.

| Operation | Purpose |
|-----------|---------|
| `cloudAgentTaskDispatch` | Start a task or continue a conversation |
| `cloudAgentTask` | Read one task. Never wakes the agent. |
| `cloudAgentTasks` | List tasks in an environment |
| `cloudAgentTaskRespond` | Answer a question or approval |
| `cloudAgentTaskCancel` | Cancel a task |
| `cloudAgentTaskRecover` | Read a result from the agent itself. Can wake the agent. |
| `cloudAgentTaskModels` | List the models a task can run on |

[Run cloud agent tasks with the Public API](/integrations/api/manage-cloud-agent-tasks) covers each operation with examples, including how to choose the model, pass context and images, get structured output, and receive webhooks.

## Limits

Railway applies these limits per user.

| Action | Limit |
|--------|-------|
| Dispatch | 60 every 5 minutes |
| Respond and cancel | 120 every 5 minutes |
| Read and list | 240 every minute |

A task that starts a new agent also counts against your workspace's cloud agent creation limit.

You can only list, read, answer, and cancel your own tasks, and a task can only run on a cloud agent you own.