Get an agent

Return a single agent by ID, including its dimensions and current extraction status. Returns 404 if the agent does not exist on this project.

On this page

HTTP request 

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

URI Parameters

Name In Required Type Description
agent_id path Yes string (uuid)  
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 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"

agent_id = "<uuid>"
project_id = "<uuid>"

resp = requests.get(
    f"{BASE_URL}/projects/{project_id}/agents/{agent_id}/",
    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

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.
inconsistency_summary No string (nullable) AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
is_draft No boolean Whether the agent is a draft. Should always be false for API callers; drafts are not returned in V1 list or retrieve responses.

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.

ValueTypeF41Enum

Type: string. One of:

  • string
  • number