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

# Run Scheduled Agent Now

> Fire one run immediately instead of waiting for the next cron tick

Launches one run of a scheduled agent right now. Returns the created session ID.

**Required scope:** `sessions:write` — the caller must also be an organization **admin or owner**.

This executes the identical code path Cloud Scheduler triggers: same template resolution, same Slack target, same orchestrator call. That is the point — a broken agent fails here, synchronously, with the reason in the response, rather than silently at its scheduled hour.

> [!NOTE]
>
> **Disabled agents run too.** Validating an agent before turning its schedule on is the main reason to use this endpoint, so `enabled` is not checked. The response echoes the agent's `enabled` state so you know which you triggered.

The run stamps `last_run_at` and `last_session_id` exactly like a scheduled tick. It is recorded with a `manual` trigger for telemetry, but is otherwise indistinguishable from a scheduled run.

## Path Parameters

**agent\_id** `string` *required*

The scheduled agent ID.

## Headers

**Authorization** `string` *required*

Bearer token. Example: `Bearer runtm_xxx`

**X-Organization-Id** `string` *required*

Organization ID.

## Response

**scheduled\_agent\_id** `string`

The agent that was run.

**session\_id** `string`

Session created by this run. Follow it with [Get Session](https://docs.runtm.com/cloud-api/sessions/get.md) or [Prompt History](https://docs.runtm.com/cloud-api/sessions/history.md).

**enabled** `boolean`

The agent's schedule state. A manual run works either way.

**trigger** `string`

Always `manual` for this endpoint.

**triggered\_at** `string`

When the run was triggered.

## Errors

| Status | Cause |
| - | - |
| `403` | Caller is not an org admin or owner |
| `404` | No such agent in this organization |
| `502` | The launch failed — `detail` carries the reason (unknown template, deleted Slack integration, sandbox capacity) |

```bash cURL theme={null}
curl -X POST "https://app.runtm.com/api/cloud/v1/scheduled-agents/sa_9f3c1a/:run" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "X-Organization-Id: org_abc123"
```

```bash CLI theme={null}
runtm-api scheduled-agents run-now sa_9f3c1a
```

```python Python theme={null}
import requests

response = requests.post(
    "https://app.runtm.com/api/cloud/v1/scheduled-agents/sa_9f3c1a:run",
    headers={
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
    },
)

if response.status_code == 502:
    # The scheduled tick would have failed the same way.
    raise RuntimeError(response.json()["detail"])

print(response.json()["session_id"])
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://app.runtm.com/api/cloud/v1/scheduled-agents/sa_9f3c1a:run",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer runtm_xxx",
      "X-Organization-Id": "org_abc123",
    },
  }
);

const data = await response.json();
console.log(data.session_id);
```

```json 200 theme={null}
{
  "scheduled_agent_id": "sa_9f3c1a",
  "session_id": "a6414511-4430-4e1f-8c51-8ea8824dadec",
  "enabled": false,
  "trigger": "manual",
  "triggered_at": "2026-07-27T18:04:11Z"
}
```

```json 502 theme={null}
{
  "detail": "Failed to launch scheduled agent: template 'gtm-machine' not found"
}
```


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