List agents

Return all agents configured on the project, ordered by most recently created first. Each agent carries its current extraction_status, so you do not need an additional request to know whether it has finished extracting.

On this page

HTTP request 

GET https://api.parsewise.ai/api/v1/projects/{project_id}/agents/

URI Parameters

Name In Required Type Description
project_id path Yes string (uuid)  

Request Header

Name Required Type Description
X-API-Key Yes string API key with the pw_live_ prefix. See Authentication.

Responses

Status Type Description
200 array<TopicInstance> —

Security

  • ApiKeyAuth — apiKey — in X-API-Key header. API key with pw_live_ prefix.

Python example 

import os
import requests

API_KEY = os.environ["PARSEWISE_API_KEY"]
BASE_URL = "https://api.parsewise.ai/api/v1"

project_id = "<uuid>"

resp = requests.get(
    f"{BASE_URL}/projects/{project_id}/agents/",
    headers={"X-API-Key": API_KEY},
)
resp.raise_for_status()
print(resp.json() if resp.content else None)

Definitions

ExtractionStatusEnum

Type: string. One of:

  • Pending
  • Processed
  • No Result

Source33eEnum

Type: string. One of:

  • CUSTOM
  • DOCUMENT
  • TAG

TopicInstance

Name Required Type Description
id Yes string (uuid) Stable identifier for the agent (UUID).
project_id Yes string (uuid) Identifier of the project this agent belongs to.
template_id Yes string (uuid) (nullable) Identifier of the agent template this agent was created from, or null if the agent was created from scratch.
dimensions Yes array<V1AgentDimensionResponse> Dimensions configured on this agent, in display order. Each dimension carries its dimension id, mapping id, name, ordered list of values, and whether values are dynamically discovered from documents (are_values_dynamic=true) or static.
created_at Yes string (date-time) Timestamp when the agent was created.
extraction_status Yes ExtractionStatusEnum Whether the agent has finished extracting against the project’s current documents. Pending while extractions are missing or in flight, Processed once all expected resolutions are present, and No Result when the agent has completed but produced no resolved values.
requires_attention Yes boolean True if any of this agent’s resolved values need attention (for example, unresolved inconsistencies between source documents).
improvement_tip_summary Yes string (nullable) Summary of the selected active improvement suggestion, or null when none is available.
name No string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions No string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
value_if_not_found No string Value shown when no extraction is found. If empty, ‘n/a’ is used.
inconsistency_summary No string (nullable) AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
agent_type No TopicInstanceAgentTypeEnum What kind of agent this is. Extraction agents extract values from documents; derived agents run an LLM prompt over other agents’ resolved values.
derived_prompt No string LLM prompt for derived agents. May contain @Name references to agents and documents.
is_evaluation No boolean Marks a derived agent as an evaluation agent: its prompt is treated as an evaluation criterion scored over the referenced agents, its value type is always number, and it is listed on the evaluation page.
derived_agent_references No array<V1DerivedAgentReference> Agents whose resolved values this derived agent consumes. On write each entry may identify its agent by agent_id, by agent_name, or by both — agent_id is tried first, and agent_name is the portable identifier to use when moving an agent configuration into another project. A reference that matches no agent in the project, or a name shared by several agents, is rejected. Both fields are always returned on read, with the name taken from the referenced agent.

TopicInstanceAgentTypeEnum

Type: string. One of:

  • extraction
  • derived

V1AgentDimensionResponse

One dimension attached to an agent, as returned in the dimensions list of an agent response.

A dimension breaks an agent’s extraction down by a categorical axis (for example, by document type or by a tag). Each entry here pairs the dimension definition (dimension_id) with how it is configured on this specific agent (allowed values, whether values are discovered dynamically from the documents, etc.).

Name Required Type Description
dimension_id Yes string (uuid) Identifier of the dimension (project-scoped dimension definition this instance attaches to the agent).
dimension_mapping_id Yes string (uuid) Identifier of this dimension’s attachment to the agent. Carries the agent-specific settings for the dimension, such as order and are_values_dynamic.
name Yes string Human-readable dimension name (e.g. “Region”, “Year”).
description Yes string Free-text description of the dimension, or empty string if none was provided.
values Yes array<string> Dimension values used to key extraction results. When are_values_dynamic is true these are discovered from the source documents; otherwise they are the static values configured on the agent.
value_count Yes integer Number of entries in values.
order Yes integer Display/declaration order of this dimension relative to the agent’s other dimensions.
are_values_dynamic Yes boolean True when the dimension’s values are dynamically discovered from documents; false when the values are statically configured.
source Yes Source33eEnum Where the dimension values come from. CUSTOM dimensions are user-defined; DOCUMENT and TAG dimensions are system-managed — their values mirror document file names or document tag values and are maintained automatically.

V1DerivedAgentReference

Name Required Type Description
agent_id No string (uuid) Identifier of the referenced agent. Always returned on read. On write, supply this or agent_name; when both are given and this one matches an agent in the project, it wins.
agent_name No string Name of the referenced agent, always returned on read from the referenced agent itself. On write it may be supplied instead of agent_id — use it when moving an agent configuration into another project, where the original ids no longer apply. Matched exactly; a name shared by several agents in the project is rejected.

ValueTypeF41Enum

Type: string. One of:

  • string
  • number