Runs an agent schedule.

POST

https://api.awork.com/api/v1/agents/:agentId/schedules/:scheduleId/run

POST

/api/v1/agents/:agentId/schedules/:scheduleId/run

curl -X POST https://api.awork.com/api/v1/agents/agentId/schedules/scheduleId/run \
     -H "Authorization: Bearer <token>"

{
  "id": "6cbb219e-839d-4d23-b273-3a78bbd842ae",
  "threadRunId": "8f934a03-8f8b-44ea-9137-3ca563bb75e8",
  "acceptedMessageId": "66fcbdc5-2ae6-43bd-b3ab-f18ccd24909a",
  "type": "custom-agent",
  "title": "Weekly client status report",
  "status": "accepted",
  "createdOn": "2026-08-29T08:00:00Z",
  "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
  "updatedOn": "2026-08-29T08:05:00Z",
  "updatedBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
  "agentId": "4d22e163-2b4a-4d47-b51c-5b2217f84f57",
  "projectId": "c907b29e-f640-4639-910d-722623fd5b4a",
  "taskId": "d88ef8fa-e549-4ca6-96d8-83f5be9d37a2",
  "clientId": "61341e18-3e3f-4efb-b471-b781e64f69f7",
  "documentId": "5a442338-8da3-49e9-a702-b45d6f829d43"
}

Immediately starts a new agent session for the selected schedule.

Required Permissions

Any authenticated user.

Immediately starts a new agent session for the selected schedule. <Check title="Required Permissions" icon="key">Any authenticated user.</Check>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agentIdstringRequiredformat: "uuid"

The agent id.

scheduleIdstringRequiredformat: "uuid"

The schedule id.

Response

idstringOptionalformat: "uuid"

The thread id.

threadRunIdstring or nullOptionalformat: "uuid"

The current run id.

acceptedMessageIdstring or nullOptionalformat: "uuid"

The accepted first-message id, or null when the thread was created without a message.

typestring or nullOptional

The thread type.

titlestring or nullOptional

The thread title.

statusenumOptional

The creation result: ready without a first message, accepted with a first message, queued when the first message waits for a run, or failed to start.

createdOnstring or nullOptionalformat: "date-time"

The creation timestamp.

createdBystringOptionalformat: "uuid"

The id of the user who created the thread.

updatedOnstring or nullOptionalformat: "date-time"

The last update timestamp.

updatedBystringOptionalformat: "uuid"

The id of the user who last updated the thread.

agentIdstring or nullOptionalformat: "uuid"

The custom agent assigned to the thread.

projectIdstring or nullOptionalformat: "uuid"

The associated project id.

taskIdstring or nullOptionalformat: "uuid"

The associated task id.

clientIdstring or nullOptionalformat: "uuid"

The associated client id.

documentIdstring or nullOptionalformat: "uuid"

The associated document id.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error