> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doctly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Document

> Retrieve detailed information about a document including download URLs.

**GET** `/api/v1/documents/{id}`

Retrieve a specific document by its ID. When the document status is `COMPLETED`, this endpoint returns signed URLs for downloading the processed output and original file.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication. Example: `Bearer YOUR_API_KEY`
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier (UUID) of the document
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.doctly.ai/api/v1/documents/123e4567-e89b-12d3-a456-426614174000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  doc_id = "123e4567-e89b-12d3-a456-426614174000"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  response = requests.get(
      f"https://api.doctly.ai/api/v1/documents/{doc_id}",
      headers=headers
  )

  document = response.json()
  print(f"Status: {document['status']}")

  if document['status'] == 'COMPLETED':
      print(f"Download: {document['output_file_url']}")
  ```

  ```javascript JavaScript theme={null}
  const docId = '123e4567-e89b-12d3-a456-426614174000';

  const response = await fetch(
    `https://api.doctly.ai/api/v1/documents/${docId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const document = await response.json();
  console.log(`Status: ${document.status}`);

  if (document.status === 'COMPLETED') {
    console.log(`Download: ${document.output_file_url}`);
  }
  ```
</CodeGroup>

## Response

<Expandable title="Document Object">
  <ResponseField name="id" type="string">
    Unique identifier (UUID) for the document
  </ResponseField>

  <ResponseField name="file_name" type="string">
    Original filename of the uploaded document
  </ResponseField>

  <ResponseField name="file_size" type="integer">
    Size of the file in bytes
  </ResponseField>

  <ResponseField name="page_count" type="integer">
    Number of pages in the document
  </ResponseField>

  <ResponseField name="status" type="string">
    Processing status: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, or `EXPIRED`
  </ResponseField>

  <ResponseField name="accuracy" type="string">
    Accuracy level used: `lite` or `ultra`
  </ResponseField>

  <ResponseField name="extractor_id" type="string">
    UUID of the extractor used (if applicable)
  </ResponseField>

  <ResponseField name="extractor" type="object">
    Extractor details when using custom extraction
  </ResponseField>

  <ResponseField name="output_file_url" type="string">
    Signed URL to download the processed output (Markdown or extraction result). Available when status is `COMPLETED`.
  </ResponseField>

  <ResponseField name="file_url" type="string">
    Signed URL to download the original uploaded file. Available when status is `COMPLETED`.
  </ResponseField>

  <ResponseField name="output_file_name" type="string">
    Filename of the processed output (e.g., `document.md` or `document.json`)
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp of creation
  </ResponseField>
</Expandable>

## Example Responses

<ResponseExample>
  ```json 200 OK — Completed theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "annual-report.pdf",
    "file_size": 4194304,
    "page_count": 48,
    "status": "COMPLETED",
    "accuracy": "ultra",
    "extractor_id": null,
    "output_file_url": "https://doctly-output.s3.amazonaws.com/...",
    "file_url": "https://doctly-files.s3.amazonaws.com/...",
    "output_file_name": "annual-report.md",
    "created_at": "2024-03-21T13:45:00Z"
  }
  ```

  ```json 200 OK — With Extractor theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "invoice.pdf",
    "file_size": 524288,
    "page_count": 2,
    "status": "COMPLETED",
    "accuracy": null,
    "extractor_id": "987fcdeb-a654-3210-9876-543210987654",
    "extractor": {
      "id": "987fcdeb-a654-3210-9876-543210987654",
      "name": "Invoice Extractor",
      "slug": "invoice-extractor",
      "cost_type": "PER_PAGE",
      "cost_credits": 5
    },
    "output_file_url": "https://doctly-output.s3.amazonaws.com/...",
    "file_url": "https://doctly-files.s3.amazonaws.com/...",
    "output_file_name": "invoice.json",
    "created_at": "2024-03-21T13:45:00Z"
  }
  ```

  ```json 200 OK — Processing theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "document.pdf",
    "file_size": 1048576,
    "page_count": 12,
    "status": "PROCESSING",
    "accuracy": "lite",
    "extractor_id": null,
    "output_file_url": null,
    "file_url": null,
    "output_file_name": null,
    "created_at": "2024-03-21T14:00:00Z"
  }
  ```

  ```json 200 OK — Failed theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "corrupted.pdf",
    "file_size": 1048576,
    "page_count": null,
    "status": "FAILED",
    "accuracy": "lite",
    "extractor_id": null,
    "output_file_url": null,
    "file_url": null,
    "output_file_name": null,
    "created_at": "2024-03-21T14:00:00Z"
  }
  ```

  ```json 200 OK — Expired theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "old-document.pdf",
    "file_size": 1048576,
    "page_count": 10,
    "status": "EXPIRED",
    "accuracy": "lite",
    "extractor_id": null,
    "output_file_url": null,
    "file_url": null,
    "output_file_name": null,
    "created_at": "2024-01-15T09:00:00Z"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "Document not found"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "detail": [
      {
        "loc": ["path", "id"],
        "msg": "value is not a valid uuid",
        "type": "type_error.uuid"
      }
    ]
  }
  ```
</ResponseExample>

## Processing Status

Documents progress through these states:

| Status       | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `PENDING`    | Document is queued for processing                          |
| `PROCESSING` | Document is actively being processed                       |
| `COMPLETED`  | Processing finished successfully — download URLs available |
| `FAILED`     | Processing failed — check the original file for issues     |
| `EXPIRED`    | Document and files have been cleaned up                    |

<Note>
  **Download URLs are temporary.** Signed URLs expire after a period of time. Fetch new URLs by calling this endpoint again if needed.
</Note>

## Polling for Completion

<CodeGroup>
  ```python Python theme={null}
  import time
  import requests

  def wait_for_document(doc_id: str, api_key: str, timeout: int = 300):
      """Poll until document processing completes."""
      headers = {"Authorization": f"Bearer {api_key}"}
      url = f"https://api.doctly.ai/api/v1/documents/{doc_id}"
      
      start = time.time()
      while time.time() - start < timeout:
          response = requests.get(url, headers=headers)
          document = response.json()
          
          if document["status"] == "COMPLETED":
              return document
          elif document["status"] == "FAILED":
              raise Exception("Document processing failed")
          
          time.sleep(5)
      
      raise TimeoutError("Document processing timed out")

  # Usage
  doc = wait_for_document("123e4567-...", "YOUR_API_KEY")
  print(f"Download: {doc['output_file_url']}")
  ```

  ```javascript JavaScript theme={null}
  async function waitForDocument(docId, apiKey, timeout = 300000) {
    const headers = { 'Authorization': `Bearer ${apiKey}` };
    const url = `https://api.doctly.ai/api/v1/documents/${docId}`;
    
    const start = Date.now();
    while (Date.now() - start < timeout) {
      const response = await fetch(url, { headers });
      const document = await response.json();
      
      if (document.status === 'COMPLETED') {
        return document;
      } else if (document.status === 'FAILED') {
        throw new Error('Document processing failed');
      }
      
      await new Promise(r => setTimeout(r, 5000));
    }
    
    throw new Error('Document processing timed out');
  }

  // Usage
  const doc = await waitForDocument('123e4567-...', 'YOUR_API_KEY');
  console.log(`Download: ${doc.output_file_url}`);
  ```
</CodeGroup>