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
required
One of:
PaginationOutput

Pagination information

object
item_count
required

The total number of items

integer
item_end
required

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

integer
item_start
required

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

integer
next_page_offset
required
One of:

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

integer
page_count
required

The total number of pages

integer
page_index
required

The index of the current page (one-based)

integer
page_offset
required

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

integer
page_size
required

The number of items per page

integer
previous_page_offset
required
One of:

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

integer
sorting
required
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_active_at last_activity_span_at last_analyzed_at last_used_at inserted_at job_title pending_clickhouse pending_s3 profile_completed_at promo_code purpose row_count size_bytes token_scope total website expires_at
nulls

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

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

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

object
delete
required

Whether the agent can be deleted

boolean
reinstate
required

Whether the agent can be reinstated from retired

boolean
retire
required

Whether the agent can be retired

boolean
update
required

Whether the agent can be updated

boolean
description
required
One of:

Agent description

string
external_identifier
required
One of:

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

string
id
required
Agent_Id

A valid agent ID

string
inserted_at
required

When the agent was created

string format: date-time
instance_counts
required
Agent_InstanceCounts
object
active
required

Number of instances with status active (running)

integer
cancelled
required

Number of instances with status cancelled

integer
complete
required

Number of instances with status complete

integer
failed
required

Number of instances with status failed

integer
finished
required

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

integer
pending
required

Number of instances with status pending

integer
terminated
required

Number of instances with status terminated

integer
total
required

Total number of agent instances

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

Agent name

string
owner_person_id
required
One of:
Person_Id

A valid person ID

string
status
required

Agent status

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

A valid team ID

string
type
required

Type of resource (always ‘agent’)

string
Allowed values: agent
updated_at
required

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
required
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 temporarily_unavailable conflict
message
required
string
status
required
string
Allowed values: error
Example
{
  "code": "bad_request",
  "status": "error"
}