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: array<object> (required); pagination: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 | Description |
|---|---|---|---|
name | string | required | |
enabled | boolean | optional | |
kind | "cron" | "event_driven" | "ad_hoc" | required | |
schedule | string | null | optional | |
target | one of 3 types | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "agentJob" (required); id: string (required); name: string (required); enabled: boolean (required); kind: "cron" | "event_driven" | "ad_hoc" (required); schedule: string | null (required); target: one of 3 types (required); nextFireAt: string | null (required); scheduleSyncState: "pending" | "synced" | "error" (required); createdByUserId: string (required); updatedByUserId: string (required); createdAt: string (required); updatedAt: string (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 | Description |
|---|---|---|---|
enabled | boolean | optional | |
kind | "cron" | "event_driven" | "ad_hoc" | optional | |
schedule | string | null | optional | |
target | one of 3 types | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 — none |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 — object — data: object (required) |
202 | Response for status 202 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 — object — data: one of 3 types (required) |
202 | Response for status 202 | application/json — object — data: one of 3 types (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
402 | Payment required. The organization has exhausted its billing-period minute budget. Upgrade the plan or wait for the period to roll over. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |