# Run a schedule now

Source: https://docs.vlayers.ai/reference/hosting/run-agent-schedule

`POST /v1/agents/{id}/schedules/{name}/run` · scope `workspace:write`

Runs one of the serving version's schedules once, now, to test it. It calls the same endpoint the same way a scheduled run does, under its own run key, and is recorded as a manual run: it is not retried and does not move the schedule's own clock. It is billed as a request like any run. Refused with 409 `not_published` when no version with a schedule is serving.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `name` | path | string | yes | The schedule name from the manifest. Example: `"daily-digest"` |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/schedules/$SCHEDULE/run" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { run } = await voicelayer.hosting.runAgentSchedule('<agent-id>', '<schedule>');
console.log(run.status);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.run_agent_schedule("<agent-id>", "<schedule>")
print(result.run.status)
```

## Response `200`

```json
{
  "run": {
    "schedule": "daily-digest",
    "fireAt": "2026-10-20T15:04:05.000Z",
    "runKey": "sched:0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78:daily-digest:2026-10-20T15:04:05.000Z",
    "status": "done",
    "attempts": 1,
    "reason": null,
    "httpStatus": 200,
    "startedAt": "2026-10-20T15:04:05.000Z",
    "endedAt": "2026-10-20T15:04:05.000Z",
    "manual": false
  }
}
```
