Scheduling

9 operations. {prefix} is the route prefix passed to MapTracon; the template uses /tracon.

GET {prefix}/api/jobs

Operation ID: TraconListJobs

Lists jobs, filtered by handler key, status, lane, or schedule.

Every queued unit of work shares this queue — scheduled runs, retention cleanups, webhook deliveries, and queued agent runs — so filter by ‘handlerKey’ to narrow it. ‘scheduleId’ returns the executions of one schedule. ‘lane’ returns only the jobs queued under that lane — the way to see whether a lane nobody’s worker subscribes to is quietly piling up. Job items are not included here; read them from the single-job endpoint. Paging is offset based, with ‘skip’ defaulting to 0 and ‘take’ to 50.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
handlerKey	query	no	string	—
status	query	no	JobStatus	—
scheduleId	query	no	string (uuid)	—
lane	query	no	string	—
skip	query	no	integer (int32)	pattern `^-?(?:0\
take	query	no	integer (int32)	pattern `^-?(?:0\

Response	Body	Headers
200 OK	application/json → array of JobRecord	—

GET {prefix}/api/jobs/{id}

Operation ID: TraconGetJob

Gets a job and its items.

This is the endpoint to poll after queuing work: it carries the job’s status and attempt count together with its items, each with its own status, so partial progress is visible while the job is still running. A failed job keeps its error text here rather than only in the logs. An unknown id, or one belonging to another tenant, returns 404.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
id	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → JobDetailResponse	—

POST {prefix}/api/jobs/{id}/cancel

Operation ID: TraconCancelJob

Cancels a job.

Only a job in the Pending, Leased, or Running status can be canceled. The executing worker checks the cancellation request between items and stops cooperatively.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
id	path	yes	string (uuid)	—

Response	Body	Headers
204 No Content	—	—

GET {prefix}/api/schedules

Operation ID: TraconListSchedules

Lists a tenant’s schedules.

Enabled and disabled schedules are returned together; ‘enabled’ tells them apart. Each entry carries ‘nextRunAt’ as computed at the last save and ‘lastRunAt’ from the last execution, which is the quickest way to see that a schedule has stopped firing. A schedule with no cron expression never fires on its own and exists only to be triggered by hand.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformRead API-key scope.

Response	Body	Headers
200 OK	application/json → array of JobSchedule	—

GET {prefix}/api/schedules/{name}

Operation ID: TraconGetSchedule

Gets a single schedule.

The response is the definition, including the stored payload the schedule fires with; the jobs it produced are read from the job endpoints, filtered by this schedule’s id. Names are scoped to the calling tenant, and an unknown name returns 404.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → JobSchedule	—

PUT {prefix}/api/schedules/{name}

Operation ID: TraconSaveSchedule

Creates or updates a schedule.

The cron expression, time zone, and lane are validated here; the next run time is computed at save time. The payload cannot exceed the MaxItemsPerJob limit. ‘lane’ defaults to ‘default’ and every job this schedule produces — cron-dispatched or manually triggered — inherits it.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (required):

• application/json → JobScheduleSaveRequest

Response	Body	Headers
200 OK	application/json → JobSchedule	—

DELETE {prefix}/api/schedules/{name}

Operation ID: TraconDeleteSchedule

Deletes a schedule.

The schedule stops firing, but jobs it already queued are not withdrawn — cancel those individually if they must not run. Job history keeps pointing at the deleted schedule’s id, so past executions stay traceable. To pause a schedule instead, save it with ‘enabled: false’. An unknown name returns 404.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
204 No Content	—	—

POST {prefix}/api/schedules/{name}/trigger

Operation ID: TraconTriggerSchedule

Runs a schedule immediately, without waiting for the cron schedule.

The job is queued, not executed inline: the response is the queued job record, so poll the job endpoint for the outcome. The body is optional — without one the schedule’s stored payload is used, and a body’s payload overrides it for this run only without changing the schedule. A trigger fires even when the schedule is disabled, and it does not move ‘nextRunAt’. The payload’s item count is capped by the same limit that applies on save.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (optional):

• application/json → JobTriggerRequest

Response	Body	Headers
200 OK	application/json → JobRecord	—

GET {prefix}/api/schedules/handler-keys

Operation ID: TraconListSchedulableHandlerKeys

Lists the handler keys a schedule may be created for.

The allow-list PUT /api/schedules/{name} enforces, so a client can offer exactly the keys that will be accepted rather than guessing. It is Tracon’s own built-in keys unless the host set TraconSchedulingOptions.HttpSchedulableHandlerKeys, and it is NOT the full set of registered handlers: a handler with no entry here runs jobs queued in process but cannot be scheduled from outside. Admin only — a consumer’s key names are deployment detail, so this list is deliberately not on the unauthenticated meta endpoint.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformRead API-key scope.

Response	Body	Headers
200 OK	application/json → array of string	—