Skip to content
PrefactorPrefactorPrefactor Docs

List agents

GET
/api/v1/agent
curl --request GET \
  --url https://app.prefactorai.com/api/v1/agent \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
idempotency_key
One of:

Optional idempotency key for ensuring request idempotency

string
risk_profile_id
One of:
RiskProfile_Id

A valid risk profile ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
team_id
One of:
Team_Id

A valid team ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
owner_person_id
One of:
Person_Id

A valid person ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
instances_active_during[start_at]
One of:
string format: date-time
Example
2024-01-01T00:00:00Z
instances_active_during[finish_at]
One of:
string format: date-time
Example
2024-01-01T00:00:00Z
sorting

Sort order; a field name, optionally prefixed with - for descending (e.g. -id). Supported fields: id, name, status, last_activity_span_at.

string

Sort order; a field name, optionally prefixed with - for descending (e.g. -id). Supported fields: id, name, status, last_activity_span_at.

pagination[offset]
integer

Zero-based offset of the first item to return.

pagination[page_size]
integer
>= 1 <= 100

Number of items to return per page (1-100).

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
pagination
One of:
PaginationOutput

Pagination information

object
item_count

The total number of items

integer
item_end

The index of the last item in the page (one-based)

integer
item_start

The index of the first item in the page (one-based)

integer
next_page_offset
One of:

The offset of the next page (null if last page)

integer
page_count

The total number of pages

integer
page_index

The index of the current page (one-based)

integer
page_offset

The offset of the first item in the page (zero-based)

integer
page_size

The number of items per page

integer
previous_page_offset
One of:

The offset of the previous page (null if first page)

integer
sorting
One of:
Sorting

Sorting information

object
direction

The direction to sort by

string
Allowed values: asc desc
field

The field to sort by (values depend on the type of list)

string
Allowed values: id status started_at finished_at email name external_identifier raised_at cleared_at severity last_activity_span_at
nulls

Where to place null values. auto leaves placement to the database default.

string
Allowed values: first last auto
status
string
Allowed values: success
summaries
Array<object>
Agent_Summary
object
available_actions
Agent_AvailableActions

Available actions for this agent based on its status and instance counts

object
delete

Whether the agent can be deleted

boolean
reinstate

Whether the agent can be reinstated from retired

boolean
retire

Whether the agent can be retired

boolean
update

Whether the agent can be updated

boolean
description
One of:

Agent description

string
external_identifier
One of:

External identifier for this agent in an external system (unique per account)

string
id
Agent_Id

A valid agent ID

string
inserted_at

When the agent was created

string format: date-time
instance_counts
Agent_InstanceCounts
object
active

Number of instances with status active (running)

integer
cancelled

Number of instances with status cancelled

integer
complete

Number of instances with status complete

integer
failed

Number of instances with status failed

integer
finished

Number of instances in a finished state (complete + failed + cancelled + terminated)

integer
pending

Number of instances with status pending

integer
terminated

Number of instances with status terminated

integer
total

Total number of agent instances

integer
last_activity_span_at
One of:
string format: date-time
name

Agent name

string
owner_person_id
One of:
Person_Id

A valid person ID

string
status

Agent status

string
Allowed values: pending active dormant retired
team_id
One of:
Team_Id

A valid team ID

string
type

Type of resource (always ‘agent’)

string
Allowed values: agent
updated_at

When the agent was last updated

string format: date-time
Example
{
  "pagination": {
    "item_count": 200,
    "item_end": 100,
    "item_start": 91,
    "next_page_offset": 110,
    "page_count": 20,
    "page_index": 10,
    "page_offset": 90,
    "page_size": 10,
    "previous_page_offset": 80
  },
  "sorting": null,
  "status": "success",
  "summaries": [
    {
      "description": "Agent description",
      "external_identifier": "workflow-abc123",
      "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "inserted_at": "2024-01-01T00:00:00Z",
      "instance_counts": {
        "active": 2,
        "cancelled": 0,
        "complete": 5,
        "failed": 0,
        "finished": 5,
        "pending": 0,
        "terminated": 0,
        "total": 10
      },
      "last_activity_span_at": "2024-01-01T00:00:00Z",
      "name": "My Agent",
      "owner_person_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "status": "pending",
      "team_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "type": "agent",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

default

Section titled “default”

Error

Media typeapplication/json
One of:
object
code
string
Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action alert_unknown alert_already_cleared invalid_value required_value idempotency_key_already_used
message
string
status
string
Allowed values: error
Example
{
  "code": "bad_request",
  "status": "error"
}