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

# List Extractions

> Query and filter extraction results with pagination

## Endpoint

```
GET /data/extractions
```

Retrieve a list of extractions with flexible filtering, sorting, and pagination. Essential for polling review status and managing extraction history.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  API key for authentication. Your unique API key.
</ParamField>

## Query Parameters

### Filters

<ParamField query="document_id" type="string">
  Filter by specific document UUID. Most efficient for single-document queries.

  ```bash theme={null}
  ?document_id=550e8400-e29b-41d4-a716-446655440000
  ```
</ParamField>

<ParamField query="status" type="string">
  Filter by extraction status.

  Options: `completed`, `processing`, `failed`, `pending`
</ParamField>

<ParamField query="needs_review" type="boolean">
  Filter by review requirement.

  ```bash theme={null}
  ?needs_review=true   # Only extractions needing review
  ?needs_review=false  # Only extractions not needing review
  ```
</ParamField>

<ParamField query="is_reviewed" type="boolean">
  Filter by review completion status.

  ```bash theme={null}
  ?is_reviewed=true    # Only reviewed extractions
  ?is_reviewed=false   # Not yet reviewed
  ```
</ParamField>

<ParamField query="original_filename" type="string">
  Filter by exact filename match.

  ```bash theme={null}
  ?original_filename=invoice-2024-001.pdf
  ```
</ParamField>

<ParamField query="created_after" type="string">
  Filter by creation timestamp (ISO 8601 format).

  ```bash theme={null}
  ?created_after=2024-01-15T00:00:00Z
  ```
</ParamField>

<ParamField query="created_before" type="string">
  Filter by creation timestamp (ISO 8601 format).

  ```bash theme={null}
  ?created_before=2024-01-31T23:59:59Z
  ```
</ParamField>

<ParamField query="organization_id" type="string">
  Filter by organization UUID. Admin-only parameter.
</ParamField>

### Sorting

<ParamField query="sort_by" type="string" default="created_at">
  Field to sort by.

  Options: `created_at`, `updated_at`, `status`, `original_filename`
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort direction.

  Options: `asc` (ascending), `desc` (descending)
</ParamField>

### Pagination

<ParamField query="skip" type="integer" default="0">
  Number of results to skip. Use for pagination.

  ```bash theme={null}
  ?skip=20  # Skip first 20 results
  ```
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum results to return. Range: 1-100.

  ```bash theme={null}
  ?limit=50  # Return max 50 results
  ```
</ParamField>

## Response

<ResponseField name="items" type="array">
  Array of extraction objects matching the query.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of extractions matching the filters (before pagination).
</ResponseField>

<ResponseField name="skip" type="integer">
  Number of results skipped.
</ResponseField>

<ResponseField name="limit" type="integer">
  Maximum results returned.
</ResponseField>

### Extraction Object

<ResponseField name="id" type="string">
  Unique extraction ID (UUID).
</ResponseField>

<ResponseField name="document_id" type="string">
  UUID of the source document.
</ResponseField>

<ResponseField name="original_filename" type="string">
  Name of the uploaded file.
</ResponseField>

<ResponseField name="status" type="string">
  Processing status: `completed`, `processing`, `failed`, `pending`.
</ResponseField>

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

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of last update.
</ResponseField>

<ResponseField name="needs_review" type="boolean">
  Whether extraction requires human review.
</ResponseField>

<ResponseField name="is_reviewed" type="boolean">
  Whether extraction has been reviewed by a human.
</ResponseField>

<ResponseField name="reviewed_at" type="string | null">
  ISO 8601 timestamp of review completion. `null` if not reviewed.
</ResponseField>

<ResponseField name="reviewed_by" type="string | null">
  UUID of user who performed review. `null` if not reviewed.
</ResponseField>

<ResponseField name="results" type="object">
  Extracted data matching the schema.
</ResponseField>

<ResponseField name="results_metadata" type="object | null">
  Metadata returned by extraction processing. Batch extractions include `batch_id` here.
</ResponseField>

<ResponseField name="reviewed_results" type="object | null">
  Corrected data after human review. `null` if not reviewed. **Use this for automation if `is_reviewed = true`**.
</ResponseField>

<ResponseField name="needs_review_metadata" type="object">
  Confidence scores and review flags. Only present in Advanced/VLM extractions.
</ResponseField>

## Examples

### Poll for Review Completion

Check if a specific document has been reviewed:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.documind.cloud/api/v1/data/extractions?document_id=550e8400-e29b-41d4-a716-446655440000&limit=1" \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

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

  response = requests.get(
      "https://api.documind.cloud/api/v1/data/extractions",
      headers={"X-API-Key": API_KEY},
      params={
          "document_id": "550e8400-e29b-41d4-a716-446655440000",
          "limit": 1
      }
  )

  data = response.json()

  if data["items"]:
      extraction = data["items"][0]
      
      if extraction["is_reviewed"]:
          print("✓ Review completed!")
          reviewed_data = extraction["reviewed_results"]
      else:
          print("⏳ Still waiting for review...")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.documind.cloud/api/v1/data/extractions?document_id=550e8400-e29b-41d4-a716-446655440000&limit=1',
    {
      headers: {
        'X-API-Key': process.env.API_KEY
      }
    }
  );

  const data = await response.json();

  if (data.items.length > 0) {
    const extraction = data.items[0];
    
    if (extraction.is_reviewed) {
      console.log('✓ Review completed!');
      const reviewedData = extraction.reviewed_results;
    } else {
      console.log('⏳ Still waiting for review...');
    }
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "items": [
      {
        "id": "extr_abc123",
        "document_id": "550e8400-e29b-41d4-a716-446655440000",
        "original_filename": "invoice-2024-001.pdf",
        "status": "completed",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:35:00Z",
        "needs_review": true,
        "is_reviewed": true,
        "reviewed_at": "2024-01-15T10:35:00Z",
        "reviewed_by": "user_xyz789",
        "results": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1250.00
        },
        "reviewed_results": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1275.00
        },
        "needs_review_metadata": {
          "confidence_scores": {
            "invoice_number": 95.2,
            "total_amount": 78.5
          },
          "review_flags": {
            "invoice_number": false,
            "total_amount": true
          }
        }
      }
    ],
    "total": 1,
    "skip": 0,
    "limit": 1
  }
  ```
</ResponseExample>

### List Pending Reviews

Get all extractions waiting for review:

```bash cURL theme={null}
curl "https://api.documind.cloud/api/v1/data/extractions?needs_review=true&is_reviewed=false&sort_by=created_at&sort_order=desc&limit=50" \
  -H 'X-API-Key: YOUR_API_KEY'
```

```python Python theme={null}
response = requests.get(
    "https://api.documind.cloud/api/v1/data/extractions",
    headers={"X-API-Key": API_KEY},
    params={
        "needs_review": True,
        "is_reviewed": False,
        "sort_by": "created_at",
        "sort_order": "desc",
        "limit": 50
    }
)

pending = response.json()
print(f"Pending reviews: {pending['total']}")

for extraction in pending["items"]:
    print(f"- {extraction['original_filename']} ({extraction['created_at']})")
```

### Filter by Date Range

Get extractions from last 24 hours:

```python Python theme={null}
from datetime import datetime, timedelta

yesterday = (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z"

response = requests.get(
    "https://api.documind.cloud/api/v1/data/extractions",
    headers={"X-API-Key": API_KEY},
    params={
        "created_after": yesterday,
        "status": "completed",
        "limit": 100
    }
)

recent = response.json()
print(f"Extractions in last 24h: {recent['total']}")
```

### Pagination Example

Iterate through all extractions:

```python Python theme={null}
def get_all_extractions(api_key, filters=None):
    """
    Fetch all extractions matching filters, handling pagination.
    """
    all_extractions = []
    skip = 0
    limit = 100
    
    while True:
        params = {
            "skip": skip,
            "limit": limit,
            **(filters or {})
        }
        
        response = requests.get(
            "https://api.documind.cloud/api/v1/data/extractions",
            headers={"X-API-Key": api_key},
            params=params
        )
        
        data = response.json()
        all_extractions.extend(data["items"])
        
        # Check if we've fetched everything
        if len(data["items"]) < limit:
            break
        
        skip += limit
    
    return all_extractions

# Usage
filters = {
    "status": "completed",
    "created_after": "2024-01-01T00:00:00Z"
}

all_completed = get_all_extractions(API_KEY, filters)
print(f"Total completed extractions: {len(all_completed)}")
```

## Common Query Patterns

### Pattern 1: Polling for Review

```python theme={null}
# Query by document_id to check specific extraction
params = {
    "document_id": document_id,
    "limit": 1
}
```

### Pattern 2: List All Pending Reviews

```python theme={null}
# Get extractions waiting for human review
params = {
    "needs_review": True,
    "is_reviewed": False,
    "sort_by": "created_at",
    "sort_order": "asc"  # Oldest first
}
```

### Pattern 3: Get Completed Reviews

```python theme={null}
# Get extractions reviewed today
from datetime import datetime

params = {
    "is_reviewed": True,
    "created_after": datetime.utcnow().replace(hour=0, minute=0).isoformat() + "Z"
}
```

### Pattern 4: Failed Extractions

```python theme={null}
# Find failed extractions for retry
params = {
    "status": "failed",
    "created_after": yesterday,
    "sort_by": "created_at",
    "sort_order": "desc"
}
```

### Pattern 5: Organization-Wide Query (Admin)

```python theme={null}
# Get all extractions for organization
params = {
    "organization_id": "org_uuid",
    "created_after": "2024-01-01T00:00:00Z",
    "limit": 100
}
```

## Response Codes

### 200 OK

Successful query, returns paginated results.

### 400 Bad Request

Invalid query parameters:

```json theme={null}
{
  "detail": "Invalid sort field: invalid_field"
}
```

### 403 Forbidden

Insufficient permissions:

```json theme={null}
{
  "detail": "You don't have permission to access these extractions"
}
```

### 500 Internal Server Error

Server-side error:

```json theme={null}
{
  "detail": "Failed to retrieve extractions. Please try again later."
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Specific Filters">
    Filter by `document_id` when possible for fastest queries:

    ```python theme={null}
    # ✓ Fast: Direct document lookup
    params = {"document_id": doc_id, "limit": 1}

    # ✗ Slower: Scan all extractions
    params = {"limit": 100}  # Then filter in code
    ```
  </Accordion>

  <Accordion title="Implement Pagination Properly">
    Handle large result sets with pagination:

    ```python theme={null}
    def fetch_page(skip=0, limit=100):
        response = requests.get(url, params={"skip": skip, "limit": limit})
        return response.json()

    # Process in batches
    skip = 0
    while True:
        page = fetch_page(skip=skip)
        process_batch(page["items"])
        
        if len(page["items"]) < limit:
            break
        skip += limit
    ```
  </Accordion>

  <Accordion title="Cache Results When Appropriate">
    For dashboard views, cache results briefly:

    ```python theme={null}
    import time

    cache = {}
    CACHE_TTL = 30  # seconds

    def get_pending_reviews_cached(api_key):
        now = time.time()
        
        if "pending" in cache:
            cached_data, timestamp = cache["pending"]
            if (now - timestamp) < CACHE_TTL:
                return cached_data
        
        # Fetch fresh data
        data = fetch_pending_reviews(api_key)
        cache["pending"] = (data, now)
        return data
    ```
  </Accordion>

  <Accordion title="Use Appropriate Limits">
    Choose limits based on use case:

    ```python theme={null}
    # Polling: Just need one result
    params = {"document_id": doc_id, "limit": 1}

    # Dashboard: Show recent items
    params = {"sort_by": "created_at", "limit": 20}

    # Batch export: Process all
    params = {"limit": 100}  # Max per page
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Extraction Details" icon="file-magnifying-glass" href="/api-reference/get-extraction">
    Retrieve complete extraction data by ID
  </Card>

  <Card title="Polling Pattern" icon="rotate" href="/api/review/polling-pattern">
    Implement review polling for automation
  </Card>

  <Card title="Update Review" icon="pen" href="/api-reference/update-review">
    Submit reviewed extraction results
  </Card>
</CardGroup>