Agent Jobs

8 operations.

Method	Endpoint	Description
GET	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs	List agent jobs
POST	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs	Create agent job
GET	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}	Get agent job
PATCH	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}	Update agent job
DELETE	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}	Delete agent job
GET	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/fires/{fireId}	Get manual agent job fire status
POST	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/runs	Run agent job now
GET	/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/stats	Get agent job run stats

List agent jobs

GET/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs

List all Agent Job schedules for a Project and Environment.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to List agent jobs.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to List agent jobs.

query

Name	Type	Required	Description
sort	"name" \| "createdAt" \| "updatedAt" \| "nextFireAt"	optional	Selects the resource field used to order results. Applies to List agent jobs.
order	"asc" \| "desc"	optional	Selects ascending or descending order for the requested sort field. Applies to List agent jobs.
limit	integer	optional	Sets the maximum number of resources returned in this page. Applies to List agent jobs.
cursor	string	optional	Opaque cursor returned by the previous page; omit it to read the first page. Applies to List agent jobs.
enabled	boolean	optional	Filters scheduled jobs by whether they are enabled. Applies to List agent jobs.

Responses

Status	Description	Body
200	Response for status 200	application/json object `agentJobs` (required): array<object> `pagination` (required): object
400	Bad Request	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Project not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object

Create agent job

POST/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs

Create a new agent job schedule for a Project Agent in an Environment.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Create agent job.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Create agent job.

Request body

required — Request body for: Create agent job.

application/json

Name	Type	Required
name	string	required
enabled	boolean	optional
kind	"cron" \| "event_driven" \| "ad_hoc"	required
schedule	one of 2 types	optional
target	one of 3 types	required

Responses

Status	Description	Body
201	Response for status 201	application/json object `type` (required): "agentJob" `id` (required): string `name` (required): string `enabled` (required): boolean `kind` (required): "cron" \| "event_driven" \| "ad_hoc" `schedule` (required): one of 2 types `target` (required): one of 3 types `nextFireAt` (required): one of 2 types `scheduleSyncState` (required): "pending" \| "synced" \| "error" `createdByUserId` (required): string `updatedByUserId` (required): string `createdAt` (required): string `updatedAt` (required): string
400	Invalid cron expression or duplicate agent job name.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Project or agent target not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object

Get agent job

GET/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}

Retrieve an agent job schedule by id.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Get agent job.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Get agent job.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Get agent job.

Responses

Status	Description	Body
200	Response for status 200	application/json object `data` (required): object
400	The request is malformed or cannot be processed.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Agent job or project not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object

Update agent job

PATCH/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}

Update an agent job schedule. Supports partial update via body fields.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Update agent job.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Update agent job.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Update agent job.

Request body

required — Request body for: Update agent job.

application/json

Name	Type	Required
enabled	boolean	optional
kind	"cron" \| "event_driven" \| "ad_hoc"	optional
schedule	one of 2 types	optional
target	one of 3 types	optional

Responses

Status	Description	Body
200	Response for status 200	application/json object `data` (required): object
400	Invalid cron expression.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Agent job, project, or agent target not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object

Delete agent job

DELETE/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}

Delete an agent job schedule.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Delete agent job.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Delete agent job.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Delete agent job.

Responses

Status	Description	Body
204	Response for status 204	none
400	The request is malformed or cannot be processed.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Agent job or project not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object

Get manual agent job fire status

GET/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/fires/{fireId}

Read the durable status of a manual operation fire. The stored originating job and caller identity remain authoritative after the mutable job is edited or deleted. This endpoint never dispatches work.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Get manual agent job fire status.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Get manual agent job fire status.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Get manual agent job fire status.
fireId	string	required	Identifies the durable manual fire whose status is being read. Applies to Get manual agent job fire status.

Responses

Status	Description	Body
200	Response for status 200	application/json getApiV1ProjectsByProjectIdEnvironmentsByEnvironmentIdAgentJobsByAgentJobIdFiresByFireId `data` (required): object
202	Response for status 202	application/json object `data` (required): object
400	The request is malformed or cannot be processed.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
403	Access denied. The authenticated user does not have permission to perform this action.	application/json PublicApiError `error` (required): object
404	Project, agent job, or fire not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object
503	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	application/json PublicApiError `error` (required): object

Run agent job now

POST/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/runs

Trigger an immediate run of a schedule, independent of the cron cadence. The scheduled nextFireAt is preserved so the regular cadence is not disturbed. The standard Idempotency-Key header is required. Reuse the same key for a transport retry: a durable manual operation fire is replayed by its fire identity and status, including lease/approval waits; agent-target claims retain their in-flight retry behavior. A changed request is rejected with 409.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Run agent job now.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Run agent job now.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Run agent job now.

header

Name	Type	Required	Description
Idempotency-Key	string	required

Responses

Status	Description	Body
200	Response for status 200	application/json postApiV1ProjectsByProjectIdEnvironmentsByEnvironmentIdAgentJobsByAgentJobIdRuns `data` (required): one of 3 types
202	Response for status 202	application/json object `data` (required): one of 3 types
400	Bad Request	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Resource not found.	application/json PublicApiError `error` (required): object
409	Request conflicts with current state of the resource, including safe deployment conflict classifications.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object
503	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	application/json PublicApiError `error` (required): object

Get agent job run stats

GET/api/v1/projects/{projectId}/environments/{environmentId}/agent-jobs/{agentJobId}/stats

Aggregate Agent run statistics for an agent job over the last rangeDays days (default 7). Returns total run count, error count, and the timestamp of the most recent failure, plus the job's lastFiredAt / nextFireAt for scheduling context.

Parameters

path

Name	Type	Required	Description
projectId	string	required	Identifies the Project that owns the addressed resource. Applies to Get agent job run stats.
environmentId	string	required	Identifies the Project environment addressed by the operation. Applies to Get agent job run stats.
agentJobId	string	required	Identifies the scheduled agent job. Applies to Get agent job run stats.

query

Name	Type	Required	Description
rangeDays	integer	optional	Sets the number of recent days included in the job statistics window. Applies to Get agent job run stats.

Responses

Status	Description	Body
200	Response for status 200	application/json object `data` (required): object
400	The request is malformed or cannot be processed.	application/json PublicApiError `error` (required): object
401	Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired	application/json PublicApiError `error` (required): object
404	Agent job or project not found.	application/json PublicApiError `error` (required): object
422	Request validation failed. Check the request body, query parameters, or path parameters.	application/json PublicApiError `error` (required): object
500	The server could not complete the request.	application/json PublicApiError `error` (required): object