---
title: "Get an agent"
method: GET
path: "/projects/{project_id}/agents/{agent_id}/"
tags: ["Agents"]
---

# Get an agent

`GET /projects/{project_id}/agents/{agent_id}/`

## Request

- Base URL: `https://api.parsewise.ai/api/v1`
- URL: `https://api.parsewise.ai/api/v1/projects/{project_id}/agents/{agent_id}/`
- Auth: API key in header `X-API-Key`

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

## Path parameters

- `agent_id` string, uuid, required
- `project_id` string, uuid, required

## Response `200`

- TopicInstance
  - `id` string, uuid, required: Stable identifier for the agent (UUID).
  - `project_id` string, uuid, required: Identifier of the project this agent belongs to.
  - `template_id` string, uuid, nullable, required: Identifier of the agent template this agent was created from, or null if the agent was created from scratch.
  - `dimensions` V1AgentDimensionResponse[], required: 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.
    - `source_agent_id` string, uuid, nullable, required: List agent that discovers the allowed values from the documents, or null when the values are configured manually.
    - `dimension_id` string, uuid, required: Identifier of the dimension (project-scoped dimension definition this instance attaches to the agent).
    - `dimension_mapping_id` string, uuid, required: 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` string, required: Human-readable dimension name (e.g. "Region", "Year").
    - `description` string, required: Free-text description of the dimension, or empty string if none was provided.
    - `values` string[], required: Dimension values used to key extraction results. When `source_agent_id` is set these follow the list agent's resolved list; otherwise they are the values configured on the agent.
    - `value_count` integer, required: Number of entries in `values`.
    - `order` integer, required: Display/declaration order of this dimension relative to the agent's other dimensions.
    - `are_values_dynamic` boolean, required: True when the values are discovered from the documents by the list agent in `source_agent_id`; false when the values are configured on the agent.
    - `allowed_values` string[], nullable, required: TAG only: the tag values this agent is restricted to, which may include tags no document has yet. Null means the agent follows all tag values.
    - `source` 'CUSTOM' | 'DOCUMENT' | 'TAG', required: * `CUSTOM` - CUSTOM * `DOCUMENT` - DOCUMENT * `TAG` - TAG
  - `created_at` string, date-time, required: Timestamp when the agent was created.
  - `extraction_status` 'Pending' | 'Processed' | 'No Result', required
  - `requires_attention` boolean, required: True if any of this agent's resolved values need attention (for example, unresolved inconsistencies between source documents).
  - `improvement_tip_summary` string, nullable, required: Summary of the selected active improvement suggestion, or null when none is available.
  - `supplying_agent_names` string[], required
  - `name` string: Human-readable name shown for the agent (e.g. "Contract value").
  - `extraction_instructions` string: Natural-language instructions describing what the agent should extract from each document.
  - `value_type` 'string' | 'number' | 'list': * `string` - string * `number` - number * `list` - list
  - `unit` string: Optional unit for numeric values (e.g. `USD`, `%`, `kg`). Used to normalise extracted values into a consistent unit and for display.
  - `examples` string: Free-form examples of expected values, used to steer the agent towards the right kind of answer.
  - `inconsistency_instructions` string: Custom instructions for inconsistency checking. If empty, default instructions will be used.
  - `resolution_instructions` string: Custom instructions for entity resolution. If empty, default instructions will be used.
  - `enable_complex_calculations_in_resolution` boolean: Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
  - `web_search_instructions` string: Web search task for each cell; required when enable_web_search is true.
  - `enable_web_search` boolean: Enable web search to supplement extraction results with data from the web.
  - `value_if_not_found` string: Value shown when no extraction is found. If empty, 'n/a' is used.
  - `inconsistency_summary` string, nullable: AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
  - `agent_type` 'extraction' | 'derived': * `extraction` - Extraction * `derived` - Derived
  - `derived_prompt` string: LLM prompt for derived agents. May contain @[Name](uuid) references to agents and documents.
  - `is_evaluation` 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` 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.
    - `agent_id` 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` 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.

---

[API](https://skmtc.dev/parsewise/apis/parsewise-api.md) - [All operations](https://skmtc.dev/parsewise/apis/parsewise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parsewise/apis/parsewise-api/revisions/5db46512debf?raw)