Skip to main content
Schedules

Run a schedule

Manually trigger one Schedule Run.

POST /api/v1/forward/schedules/{schedule_id}/run Creates a Schedule Run immediately without changing the Schedule's trigger policy. The endpoint returns when the Run record is created, not when execution finishes.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeNoapplication/json if a body is sent.
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Path parameters

ParameterTypeRequiredDescription
schedule_idstringYesForward Schedule ID.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd/run' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example response

HTTP 200 OK 
{
  "id": "srun_019f00112233445566778899aabbccdd",
  "schedule_id": "sched_019f00112233445566778899aabbccdd",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "status": "pending",
  "trigger_context": {
    "type": "manual"
  },
  "push_status": "skipped",
  "push_finished_at": "2026-06-22T01:00:21Z",
  "attempt": 1,
  "triggered_at": "2026-06-22T12:00:00Z",
  "created_at": "2026-06-22T12:00:00Z"
}

Response fields

Returns the created Schedule Run object. A newly created Run starts at attempt=1. If the Schedule is configured with execution.max_attempts=2, the server may automatically retry once after the first execution fails. Whether a retry actually occurs is determined by the attempt field returned by Get Schedule Run or List Schedule Runs.

Errors

HTTPTypeCodeTrigger
401authentication_errorauthentication_requiredPAT or SAT invalid or expired.
404not_found_errorschedule_not_foundSchedule does not exist.
409invalid_request_errorschedule_archivedSchedule is archived.
409invalid_request_errorschedule_not_activeSchedule is paused.

Notes

  • If the Schedule has reached execution.max_concurrent_runs, Forward still creates a Run with status=skipped and error.type=concurrency_limit_reached.
  • Poll Get Schedule Run until status is completed, failed, or skipped.

Get schedule run

List schedule runs

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference