List agent spans

GET

/api/v1/agent_spans

const url = 'https://app.prefactorai.com/api/v1/agent_spans?agent_instance_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&agent_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&include_summaries=false&include_risk_level=false&redacted=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://app.prefactorai.com/api/v1/agent_spans?agent_instance_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&agent_id=013xrzp12g3nqk8ns6jadrqmpgrjkeny&include_summaries=false&include_risk_level=false&redacted=false' \
  --header 'Authorization: Bearer <token>'

Authorizations

authorization

Parameters

Query Parameters

agent_instance_id

AgentInstance_Id

A valid agent instance ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

agent_id

Agent_Id

A valid agent ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

environment_id

One of:

Environment_Id
Null

Environment_Id

A valid environment ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

idempotency_key

One of:

string
Null

Optional idempotency key for ensuring request idempotency

string

start_time

end_time

purpose

One of:

string
Null

string

Allowed values: activity quality alert

Example

activity

alert_id

One of:

Alert_Id
Null

Alert_Id

A valid alert ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

sorting

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

string

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

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).

include_summaries

Include human-readable summaries from schema templates (default: false for performance)

boolean

include_risk_level

When true, score each activity-purpose span against the agent’s risk profile and populate risk_level and risk_score on the summary.

boolean

redacted

When true, strip sensitive values from payload and result_payload, and render the summary with redaction labels. Defaults to false.

boolean

Responses

200

Success

application/json

object

pagination

required

One of:

PaginationOutput
Null

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:

integer
Null

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:

integer
Null

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

integer

sorting

required

One of:

Sorting
Null

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>

AgentSpan_Summary

object

account_id

required

Account_Id

A valid account ID

string

agent_id

required

Agent_Id

A valid agent ID

string

agent_instance_id

required

AgentInstance_Id

A valid agent instance ID

string

data_risk

required

One of:

DataRisk
Null

DataRisk

object

action_profile

required

ActionProfile

object

create_data

required

Creates data

string

Allowed values: unknown allowed disallowed

destroy_data

required

Destroys data

string

Allowed values: unknown allowed disallowed

external_communication

required

Sends external communications

string

Allowed values: unknown allowed disallowed

financial_transactions

required

Performs financial transactions

string

Allowed values: unknown allowed disallowed

read_data

required

Reads data

string

Allowed values: unknown allowed disallowed

update_data

required

Updates data

string

Allowed values: unknown allowed disallowed

params_data_categories

required

DataCategories

object

authentication_and_secrets

required

Authentication and secrets present

string

Allowed values: unknown included excluded

behavioural_and_inferred

required

Behavioural and inferred data present

string

Allowed values: unknown included excluded

classification

required

Classification level

string

Allowed values: unknown public internal confidential restricted secret

contact_information

required

Contact information present

string

Allowed values: unknown included excluded

criminal_justice

required

Criminal justice data present

string

Allowed values: unknown included excluded

financial_information

required

Financial information present

string

Allowed values: unknown included excluded

gdpr_biometric_for_identification

required

GDPR: biometric data for identification

string

Allowed values: unknown included excluded

gdpr_genetic_data

required

GDPR: genetic data

string

Allowed values: unknown included excluded

gdpr_political_opinions

required

GDPR: political opinions

string

Allowed values: unknown included excluded

gdpr_racial_or_ethnic_origin

required

GDPR: racial or ethnic origin

string

Allowed values: unknown included excluded

gdpr_religious_or_philosophical_beliefs

required

GDPR: religious or philosophical beliefs

string

Allowed values: unknown included excluded

gdpr_sex_life_or_sexual_orientation

required

GDPR: sex life or sexual orientation

string

Allowed values: unknown included excluded

gdpr_trade_union_membership

required

GDPR: trade union membership

string

Allowed values: unknown included excluded

health_and_medical

required

Health and medical data present

string

Allowed values: unknown included excluded

location_and_tracking

required

Location and tracking data present

string

Allowed values: unknown included excluded

minors_data

required

Minors data present

string

Allowed values: unknown included excluded

organisational_confidential

required

Organisational confidential data present

string

Allowed values: unknown included excluded

personal_identifiers

required

Personal identifiers present

string

Allowed values: unknown included excluded

result_data_categories

required

DataCategories

object

authentication_and_secrets

required

Authentication and secrets present

string

Allowed values: unknown included excluded

behavioural_and_inferred

required

Behavioural and inferred data present

string

Allowed values: unknown included excluded

classification

required

Classification level

string

Allowed values: unknown public internal confidential restricted secret

contact_information

required

Contact information present

string

Allowed values: unknown included excluded

criminal_justice

required

Criminal justice data present

string

Allowed values: unknown included excluded

financial_information

required

Financial information present

string

Allowed values: unknown included excluded

gdpr_biometric_for_identification

required

GDPR: biometric data for identification

string

Allowed values: unknown included excluded

gdpr_genetic_data

required

GDPR: genetic data

string

Allowed values: unknown included excluded

gdpr_political_opinions

required

GDPR: political opinions

string

Allowed values: unknown included excluded

gdpr_racial_or_ethnic_origin

required

GDPR: racial or ethnic origin

string

Allowed values: unknown included excluded

gdpr_religious_or_philosophical_beliefs

required

GDPR: religious or philosophical beliefs

string

Allowed values: unknown included excluded

gdpr_sex_life_or_sexual_orientation

required

GDPR: sex life or sexual orientation

string

Allowed values: unknown included excluded

gdpr_trade_union_membership

required

GDPR: trade union membership

string

Allowed values: unknown included excluded

health_and_medical

required

Health and medical data present

string

Allowed values: unknown included excluded

location_and_tracking

required

Location and tracking data present

string

Allowed values: unknown included excluded

minors_data

required

Minors data present

string

Allowed values: unknown included excluded

organisational_confidential

required

Organisational confidential data present

string

Allowed values: unknown included excluded

personal_identifiers

required

Personal identifiers present

string

Allowed values: unknown included excluded

finished_at

required

One of:

string
Null

When the span finished (null if still in progress)

string format: date-time

required

AgentSpan_Id

A valid agent span ID

string

parent_span_id

required

One of:

AgentSpan_Id
Null

AgentSpan_Id

A valid agent span ID

string

payload

required

Span payload data (arbitrary JSON object)

object

key

additional properties

any

payload_byte_size_estimate

required

Approximate JSON-encoded byte size of the span’s stored payload columns. This is an estimate, not an exact on-disk size.

integer

purpose

required

Purpose of the span: ‘activity’ (normal agent activity), ‘quality’ (system-written span recording an agent instance quality payload update), or ‘alert’ (system-written span recording an alert lifecycle event). Quality-purpose and alert-purpose spans are excluded from standard span metrics.

string

Allowed values: activity quality alert

result_payload

required

One of:

object
Null

Result payload (arbitrary JSON), only present when span is finished

object

key

additional properties

any

risk_level

required

One of:

string
Null

Risk level for this span based on its schema’s data_risk and the agent’s risk profile. Only populated for activity-purpose spans when the request includes include_risk_level, the agent has a risk profile, and the span’s schema has scoreable data_risk.

string

Allowed values: low medium high critical

risk_score

required

One of:

number
Null

Numeric risk score for this span based on its schema’s data_risk and the agent’s risk profile. Only populated for activity-purpose spans, together with risk_level, when the request includes include_risk_level.

number

schema_name

required

Name of the schema for this span

string

schema_title

required

Human-readable title for the schema (from JSON schema, defaults to schema_name)

string

sensitive_encoding

required

When true, both payload and result_payload should be interpreted as containing sensitive markers as per the specification

boolean

started_at

required

When the span started

string format: date-time

status

required

Status of the span: ‘active’ (started but not finished), ‘complete’ (finished successfully), ‘failed’ (ended with failure), or ‘cancelled’ (started but cancelled before completion)

string

Allowed values: active complete failed cancelled

summary

required

One of:

string
Null

Human-readable summary rendered from the schema template using payload and result_payload (null when template is missing). When the request sets redacted to true, sensitive values in the summary are replaced with redaction labels.

string

type

required

Type of resource (always ‘agent_span’)

string

Allowed values: agent_span

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_instance_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "data_risk": null,
      "finished_at": "2024-01-01T00:00:00Z",
      "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "parent_span_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
      "purpose": "activity",
      "result_payload": null,
      "risk_level": "low",
      "risk_score": 40,
      "schema_name": "llm",
      "schema_title": "LLM",
      "started_at": "2024-01-01T00:00:00Z",
      "status": "active",
      "summary": null,
      "type": "agent_span"
    }
  ]
}

default

Error

application/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"
}