Skip to content

List agent instances

GET
/api/v1/agent_instance
curl --request GET \
--url 'https://app.prefactorai.com/api/v1/agent_instance?agent_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&agent_version_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&pagination%5Bpage_with_id%5D=013xrzp12g3nqk8ns6jadrqmpgrjkeny&include_risk_score=false&include_alert_count=false' \
--header 'Authorization: Bearer <token>'
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
idempotency_key
One of:

Optional idempotency key for ensuring request idempotency

string
agent_version_id
AgentVersion_Id

A valid agent version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
active_during[start_at]
One of:
string format: date-time
Example
2024-01-01T00:00:00Z
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, status, last_activity_span_at.

string

Sort order; a field name, optionally prefixed with - for descending (e.g. -id). Supported fields: id, 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).

pagination[page_with_id]
AgentInstance_Id

A valid agent instance ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny

Return the page that contains this id (page-aligned from offset 0). Do not combine with pagination[offset].

include_risk_score

Include risk_score in each summary (null when the agent has no risk profile or scoring inputs are unavailable)

boolean
include_alert_count

Include raised_alert_count in the response (counts only alerts the caller may show)

boolean
statuses

When set, return only instances with one of these statuses. When omitted, return every status.

Array<string>
Allowed values: preparing pending active complete failed cancelled terminated

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 mode agent_instance_id job_title pending_clickhouse pending_s3 profile_completed_at promo_code purpose row_count size_bytes token_scope total website expires_at path revision_number spans_in_range failed_in_range last_span_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>
AgentInstance_Summary
object
account_id
required
Account_Id

A valid account ID

string
agent_id
required
Agent_Id

A valid agent ID

string
agent_risk_version_id
required
One of:
AgentRiskVersion_Id

A valid agent risk version ID

string
agent_version_id
required
AgentVersion_Id

A valid agent version ID

string
environment_id
required
Environment_Id

A valid environment ID

string
execution_mode
required

Whether Prefactor executes this instance (hosted) or an external agent reports telemetry (remote)

string
Allowed values: hosted remote
external_identifier
required
One of:

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

string
finished_at
required
One of:

When the agent instance finished (null if still in progress)

string format: date-time
id
required
AgentInstance_Id

A valid agent instance ID

string
inserted_at
required

When the agent instance was created

string format: date-time
last_activity_span_at
required
One of:
string format: date-time
purpose
required

Why this instance ran: ‘live’ for an actual agent run, ‘smoke_test’ for a pipeline check, or ‘eval’ for an evaluation run

string
Allowed values: live smoke_test eval
raised_alert_count
required
One of:
integer
risk_score
required
One of:
AgentInstance_RiskScore
object
all_data_categories
required

Unique included data categories across params and results of span types that ran, in canonical order

Array<string>
Allowed values: personal_identifiers contact_information financial_information health_and_medical criminal_justice authentication_and_secrets organisational_confidential minors_data location_and_tracking behavioural_and_inferred gdpr_racial_or_ethnic_origin gdpr_political_opinions gdpr_religious_or_philosophical_beliefs gdpr_trade_union_membership gdpr_genetic_data gdpr_biometric_for_identification gdpr_sex_life_or_sexual_orientation
allowed_actions
required

Actions allowed by at least one span type that ran in this instance, in canonical order

Array<string>
Allowed values: create_data read_data update_data destroy_data financial_transactions external_communication
any_assessable
required

Whether the instance has at least one span type with scoreable data_risk

boolean
critical_threshold
required

Critical threshold from the agent’s risk profile ruleset

number
peak_classification
required
One of:

Peak observed data risk classification across all spans in this instance. null if no spans have executed.

string
Allowed values: unknown public internal confidential restricted secret
per_type
required

Per-schema-type score breakdown

Array<object>
AgentInstance_RiskScore_PerType
object
count
required

Number of span invocations for this schema type

integer
risk_level
required

Risk level bucket for this schema type’s per-invocation score

string
Allowed values: low medium high critical
schema_name
required

Span type schema name

string
total_contribution
required

Type_score multiplied by count

number
type_score
required

Risk score for a single invocation of this schema type

number
risk_level
required
One of:

Overall risk level bucket for this instance, or null when not assessable

string
Allowed values: low medium high critical
total_score
required

Total risk score across all span types for this instance

number
started_at
required
One of:

When the agent instance started (null if not started yet)

string format: date-time
status
required

Status of the agent instance: ‘preparing’ (input not ready yet), ‘pending’ (ready to start), ‘active’ (started but not finished), ‘complete’ (finished successfully), ‘failed’ (ended with failure), ‘cancelled’ (never started, cancelled), or ‘terminated’ (externally terminated)

string
Allowed values: preparing pending active complete failed cancelled terminated
termination_reason
required
One of:

Reason for termination (only present when status is ‘terminated’)

string
type
required

Type of resource (always ‘agent_instance’)

string
Allowed values: agent_instance
updated_at
required

When the agent instance 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": [
{
"account_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"agent_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"agent_risk_version_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"agent_version_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"environment_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"execution_mode": "hosted",
"external_identifier": "run-abc123",
"finished_at": "2024-01-01T00:00:00Z",
"id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
"inserted_at": "2024-01-01T00:00:00Z",
"last_activity_span_at": "2024-01-01T00:00:00Z",
"purpose": "live",
"raised_alert_count": null,
"risk_score": null,
"started_at": "2024-01-01T00:00:00Z",
"status": "preparing",
"termination_reason": "User requested termination",
"type": "agent_instance",
"updated_at": "2024-01-01T00:00:00Z"
}
]
}

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 invalid_state 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"
}