> ## Documentation Index
> Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Agent Thread
> Returns a thread's current status, and once it has finished, the agent's answer, its citations, and any files it generated.
Returns `200` for every thread you can read, including one still running. Poll until `status` is terminal rather than matching a specific non-terminal value.
### Permissions
Requires `Agents and workflows API` and `Use agents and workflows` permissions. If these permissions are not available to select, contact [support@harvey.ai](mailto:support@harvey.ai).
## OpenAPI
````yaml /agents_api.json get /api/v1/agent_threads/{thread_id}
openapi: 3.0.1
info:
title: Harvey Agents API
description: >-
Run Harvey text-based agents programmatically. Discover the agents available
to your workspace, start an agent on a prompt with optional documents, then
poll for the answer, its citations, and any files the agent produced.
version: 1.0.0
contact:
email: support@harvey.ai
servers:
- url: https://api.harvey.ai
description: Harvey API server
security: []
paths:
/api/v1/agent_threads/{thread_id}:
get:
tags:
- Agents
summary: Get Agent Thread
description: >-
Returns a thread's current status, and once it has finished, the agent's
answer, its citations, and any files it generated.
Returns `200` for every thread you can read, including one still
running. Poll until `status` is terminal rather than matching a specific
non-terminal value.
operationId: getAgentThread
parameters:
- name: thread_id
in: path
required: true
description: The unique identifier of the agent thread.
schema:
type: integer
example: 1671319
responses:
'200':
description: The thread, with its answer once it has finished
content:
application/json:
schema:
$ref: '#/components/schemas/AgentThread'
examples:
inProgress:
summary: While the agent is still running
value:
id: 1671319
status: IN_PROGRESS
agent_id: 01a0d9c9-3334-7036-ad4a-d14db13b93ba
client_matter_id: null
harvey_url: https://app.harvey.ai/assistant/assist/1671319
created_at: '2026-10-09T05:12:59.454218Z'
output: null
error: null
files:
- name: northwind-msa.pdf
processing_status: PROCESSING
failure_category: null
error: null
completed:
summary: After the agent has finished
value:
id: 1671319
status: COMPLETED
agent_id: 01a0d9c9-3334-7036-ad4a-d14db13b93ba
client_matter_id: null
harvey_url: https://app.harvey.ai/assistant/assist/1671319
created_at: '2026-10-09T05:12:59.454218Z'
error: null
files:
- name: northwind-msa.pdf
processing_status: READY_TO_QUERY
failure_category: null
error: null
output:
text: >-
The agreement permits termination on 30 days' written
notice. [1]
citations:
- citation_number: 1
file_id: 66fead63-460e-4426-a179-39c70b224a99
file_name: northwind-msa.pdf
citation_page: 12
citation_quote: >-
Either party may terminate this Agreement upon
thirty days' written notice.
files:
- file_id: bdb2f894-3c3a-4897-babb-fe755df6ee7d
file_name: termination-summary.docx
content_type: >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
'401':
description: Unauthorized - Invalid or missing API token, or a missing permission
'404':
description: >-
Not Found - No thread you can read has this id. Also returned for a
thread past its retention period, a Harvey conversation that was not
created through this API, and when the Agents API is not enabled for
your workspace
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Thread not found
'429':
description: Too Many Requests - Rate limit exceeded
'500':
description: Internal Server Error
security:
- bearerAuth: []
components:
schemas:
AgentThread:
type: object
description: A thread and the agent run it holds.
properties:
id:
type: integer
description: The unique identifier of the agent thread.
status:
$ref: '#/components/schemas/AgentThreadStatus'
agent_id:
type: string
format: uuid
nullable: true
description: The agent this thread ran. Null until the agent begins executing.
client_matter_id:
type: string
format: uuid
nullable: true
description: >-
The client matter this thread is attributed to, as a UUID, even if
you supplied a name. Null when none was supplied.
harvey_url:
type: string
format: uri
description: >-
Link to the thread in the Harvey web app, for handing the work to a
person.
created_at:
type: string
format: date-time
description: When the thread was created.
output:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/AgentThreadOutput'
description: >-
What the agent produced. Null until `status` is terminal, and on a
thread that produced no answer.
error:
type: string
nullable: true
description: >-
Why the thread did not complete. Null unless `status` is `ERRORED`
or `CANCELLED`.
files:
type: array
description: >-
The documents you attached, each with the processing status recorded
for it. Generated files live under `output.files` instead.
items:
$ref: '#/components/schemas/AgentThreadInputFile'
AgentThreadStatus:
type: string
description: >-
Lifecycle state of a thread. `COMPLETED`, `ERRORED` and `CANCELLED` are
terminal.
enum:
- PENDING
- IN_PROGRESS
- COMPLETED
- ERRORED
- CANCELLED
AgentThreadOutput:
type: object
description: What a finished thread produced.
properties:
text:
type: string
description: >-
The agent's answer, with each source rendered as a `[N]` marker that
matches a `citation_number` in `citations`.
citations:
type: array
description: >-
Sources behind the answer, ordered by where their marker first
appears in `text`. A source the answer never marked up sorts after
those, keeping its `citation_number` null.
items:
$ref: '#/components/schemas/AgentThreadCitation'
files:
type: array
description: Files the agent generated, in the order it produced them.
items:
$ref: '#/components/schemas/AgentThreadGeneratedFile'
AgentThreadInputFile:
type: object
description: A document you attached.
properties:
name:
type: string
description: The file name as you uploaded it.
processing_status:
type: string
description: >-
Where the file is in processing. The agent can read it at
`READY_TO_QUERY`, and is still waiting on it at `UPLOADED` or
`PROCESSING`.
enum:
- UPLOADED
- PROCESSING
- READY_TO_QUERY
- READY_TO_REVIEW
- RECOVERABLE_FAILURE
- UNRECOVERABLE_FAILURE
failure_category:
type: string
nullable: true
description: >-
Why the file failed, or null if it did not. This is the verdict —
check it rather than `processing_status`, which can report a success
state for a file that still failed.
enum:
- UNSUPPORTED_FILE_TYPE
- FILE_SIZE_TOO_LARGE
- EMPTY_DOCUMENT
- FILE_TYPE_MISMATCH
- PASSWORD_PROTECTED
- CERTIFICATE_ENCRYPTED
- OCR_ERROR
- DOCUMENT_TOO_LARGE
- UPLOAD_NO_FILENAME
- UPLOAD_FILE_TOO_LARGE
- UPLOAD_INVALID_FILE_TYPE
- UPLOAD_PATH_TOO_LONG
- OTHER_UPLOAD_ERROR
- RECOVERABLE_ERROR
- INTERNAL_ERROR
- DMS_DOWNLOAD_ERROR
- UNKNOWN
- DMS_SYNC_VALIDATION_UNKNOWN
- FILE_CORRUPTED
- IMG_NO_TEXT
- CANNOT_PROCESS_FILE
- OCR_PROCESSING_LIMIT
- null
error:
type: string
nullable: true
description: A readable message for the failure. Null when the file did not fail.
AgentThreadCitation:
type: object
description: >-
One source behind the answer, keyed to its `[N]` marker in the answer
text. Every field is nullable, because a source carries only what its
material can supply — a web result has no page, for example.
properties:
citation_number:
type: integer
nullable: true
description: >-
The `[N]` marker this source appears as in `output.text`. Null when
the answer text never marked this source up.
file_id:
type: string
format: uuid
nullable: true
description: >-
Identifier of the source document. Null when the source is not a
document in Harvey.
file_name:
type: string
nullable: true
description: >-
Name of the source document. Null when the source is not a document
in Harvey.
citation_page:
type: integer
nullable: true
description: >-
The page number printed on the document, counting from 1. Null when
the source has no pages.
citation_quote:
type: string
nullable: true
description: >-
The quoted passage. `` wraps the quoted span inside its
surrounding context. Null when the source carries no quotable
passage.
AgentThreadGeneratedFile:
type: object
description: A file the agent produced.
properties:
file_id:
type: string
format: uuid
description: >-
Identifier of the generated file. Pass this to `POST
/api/v1/files/download` to fetch the bytes.
file_name:
type: string
nullable: true
description: >-
The file name the agent gave the document. Null when the agent
produced the file without naming it.
content_type:
type: string
nullable: true
description: >-
MIME type of the file, such as
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
Null when the type was not recorded; read it from the download
response instead.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Token
````
## Related topics
- [Create Agent Thread](/api-reference/agents/create-agent-thread.md)
- [Rate Limits](/api-reference/ratelimits.md)
- [Get Agent](/api-reference/agents/get-agent.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.