Skip to content
PrefactorPrefactorPrefactor Docs

Create a new agent span

POST
/api/v1/agent_spans
curl --request POST \
  --url https://app.prefactorai.com/api/v1/agent_spans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agent_instance_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "finished_at": "2024-01-01T00:00:00Z", "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "parent_span_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "payload": {}, "result_payload": null, "schema_name": "llm", "sensitive_encoding": false, "started_at": "2024-01-01T00:00:00Z", "status": "pending" }'

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
AgentSpan_DetailsForCreate
object
agent_instance_id
required
AgentInstance_Id

A valid agent instance ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
finished_at
One of:

When the span finished (ISO 8601 format). If not provided, span is still in progress.

string format: date-time
Example
2024-01-01T00:00:00Z
id
One of:
AgentSpan_Id

A valid agent span ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
parent_span_id
One of:
AgentSpan_Id

A valid agent span ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
payload
required

Span payload data (arbitrary JSON object)

object
key
additional properties
any
result_payload
One of:

Result payload (arbitrary JSON). Only valid when status is complete, failed, or cancelled.

object
key
additional properties
any
schema_name
required

Name of the schema for this span

string
Example
llm
sensitive_encoding

When true, payload and result_payload are parsed as sensitive-encoded JSON; values marked with $sensitive are extracted and stored securely, separate from the rest of the payload. Defaults to false.

boolean
started_at
One of:

When the span started (ISO 8601 format). If not provided, current time is used.

string format: date-time
Example
2024-01-01T00:00:00Z
status
required

Status of the span (required)

string
Allowed values: pending active complete failed cancelled
Example
active

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
control
AgentSpan_Control
object
reason
required
string
terminate
required
boolean
details
AgentSpan_Details
object
account_id
Account_Id

A valid account ID

string
agent_id
Agent_Id

A valid agent ID

string
agent_instance_id
AgentInstance_Id

A valid agent instance ID

string
data_risk
One of:
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
One of:

When the span finished (null if still in progress)

string format: date-time
id
AgentSpan_Id

A valid agent span ID

string
parent_span_id
One of:
AgentSpan_Id

A valid agent span ID

string
payload

Span payload data (arbitrary JSON object)

object
key
additional properties
any
payload_byte_size_estimate

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

integer
purpose

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

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

object
key
additional properties
any
schema_name

Name of the schema for this span

string
schema_title

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

string
sensitive_encoding

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

boolean
started_at
One of:

When the span started (null when status is pending)

string format: date-time
status

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

string
Allowed values: pending active complete failed cancelled
summary
One of:

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

Type of resource (always ‘agent_span’)

string
Allowed values: agent_span
status
string
Allowed values: success
Example
{
  "details": {
    "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,
    "schema_name": "llm",
    "schema_title": "LLM",
    "started_at": "2024-01-01T00:00:00Z",
    "status": "pending",
    "summary": null,
    "type": "agent_span"
  },
  "status": "success"
}

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