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

# Get elements

> Retrieve parsed elements (chunks/partitions) of a source via the Graphor REST API

The **Get elements** endpoint returns the parsed elements (chunks/partitions) of a source in the same format as [Get build status](/api-reference/sources/upload#get-build-status) elements. Each item includes explicit fields: `element_id`, `element_type`, `text`, `markdown`, `html`, `img_base64` (optional), `position`, `page_number`, `bounding_box`, `page_layout`, and more.

## Endpoint overview

<CardGroup cols={2}>
  <Card title="HTTP Method" icon="list">
    **GET**
  </Card>

  <Card title="Endpoint URL" icon="link">
    **[https://sources.graphorlm.com/get-elements](https://sources.graphorlm.com/get-elements)**
  </Card>
</CardGroup>

## Authentication

This endpoint requires authentication using an API token. Include your API token as a Bearer token in the `Authorization` header.

<Note>
  Learn how to create and manage API tokens in the [API Tokens guide](/guides/api-tokens).
</Note>

## Request format

### Headers

| Header          | Value                   | Required |
| --------------- | ----------------------- | -------- |
| `Authorization` | `Bearer YOUR_API_TOKEN` | Yes      |

### Query parameters

| Parameter             | Type             | Required | Description                                                                                     |
| --------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `file_id`             | string           | Yes      | Unique identifier of the source                                                                 |
| `page`                | integer          | No       | 1-based page number. Use with `page_size` to enable pagination                                  |
| `page_size`           | integer          | No       | Number of elements per page (1–100). Use with `page`                                            |
| `suppress_img_base64` | boolean          | No       | When `true`, `img_base64` is omitted from each element (reduces payload size)                   |
| `type`                | string           | No       | Filter by element type (e.g. `NarrativeText`, `Title`, `Table`)                                 |
| `page_numbers`        | list of integers | No       | Restrict to specific page numbers (repeat param for multiple: `?page_numbers=1&page_numbers=2`) |
| `elementsToRemove`    | list of strings  | No       | Element types to exclude (repeat param for multiple)                                            |

When `page` and `page_size` are omitted, all elements are returned (no pagination). When only one is provided, pagination is not applied.

## Response format

### Success response (200 OK)

Paginated response with items as `BuildStatusElement` (same shape as elements in [Get build status](/api-reference/sources/upload#get-build-status)):

```json theme={null}
{
  "items": [
    {
      "element_id": "0ee55f099828817da5485796b339aeab",
      "element_type": "Title",
      "text": "Attention Is All You Need",
      "markdown": "## Attention Is All You Need",
      "html": "<h2>Attention Is All You Need</h2>",
      "img_base64": null,
      "position": 5,
      "page_number": 1,
      "bounding_box": {
        "left": 211.488,
        "top": 148.43,
        "width": 188.41,
        "height": 17.22
      },
      "page_layout": { "width": 612.0, "height": 792.0 },
      "page_annotation": null,
      "page_keywords": null,
      "page_topics": null,
      "metadata": {}
    }
  ],
  "total": 393,
  "page": 1,
  "page_size": 10,
  "total_pages": 40
}
```

### Pagination fields

| Field         | Type            | Description                                                           |
| ------------- | --------------- | --------------------------------------------------------------------- |
| `items`       | array           | Elements in the current page (or all elements if pagination not used) |
| `total`       | integer         | Total number of elements (matching filters)                           |
| `page`        | integer \| null | Current page (1-based), or null when no pagination                    |
| `page_size`   | integer \| null | Elements per page, or null when no pagination                         |
| `total_pages` | integer \| null | Total pages, or null when no pagination                               |

### Element fields (BuildStatusElement)

| Field             | Type            | Description                                                         |
| ----------------- | --------------- | ------------------------------------------------------------------- |
| `element_id`      | string \| null  | Unique identifier for the element                                   |
| `element_type`    | string \| null  | Type: e.g. `Title`, `NarrativeText`, `Table`, `Image`               |
| `text`            | string          | Plain text content                                                  |
| `markdown`        | string \| null  | Markdown representation when available                              |
| `html`            | string \| null  | HTML representation when available                                  |
| `img_base64`      | string \| null  | Base64-encoded image data (omitted when `suppress_img_base64=true`) |
| `position`        | integer \| null | Order/position within the document                                  |
| `page_number`     | integer \| null | Page number (1-based) where the element appears                     |
| `bounding_box`    | object \| null  | Bounding box (e.g. left, top, width, height) when available         |
| `page_layout`     | object \| null  | Page dimensions (width, height) when available                      |
| `page_annotation` | string \| null  | Annotation/summary for the page                                     |
| `page_keywords`   | array \| null   | Keywords extracted for the page                                     |
| `page_topics`     | array \| null   | Topics extracted for the page                                       |
| `metadata`        | object          | Additional metadata                                                 |

## Element types

| Type                | Description                            |
| ------------------- | -------------------------------------- |
| `Title`             | Document and section titles            |
| `NarrativeText`     | Main body paragraphs                   |
| `ListItem`          | Bullet or numbered list items          |
| `Table`             | Data tables                            |
| `TableRow`          | Rows within tables                     |
| `Image`             | Pictures or graphics                   |
| `Header`            | Header content                         |
| `Footer`            | Footer content                         |
| `Formula`           | Mathematical formulas                  |
| `FigureCaption`     | Captions for figures                   |
| `PageNumber`        | Page numbering                         |
| `CodeSnippet`       | Code segments                          |
| `Link`              | Hyperlinks                             |
| `UncategorizedText` | Text that doesn't fit other categories |

## Code examples

### JavaScript/Node.js

```javascript theme={null}
const getElements = async (apiToken, fileId, options = {}) => {
  const params = new URLSearchParams({ file_id: fileId });
  if (options.page != null) params.set("page", String(options.page));
  if (options.pageSize != null) params.set("page_size", String(options.pageSize));
  if (options.suppressImgBase64) params.set("suppress_img_base64", "true");
  if (options.type) params.set("type", options.type);
  if (options.pageNumbers?.length) options.pageNumbers.forEach((n) => params.append("page_numbers", String(n)));
  if (options.elementsToRemove?.length) options.elementsToRemove.forEach((t) => params.append("elementsToRemove", t));

  const url = `https://sources.graphorlm.com/get-elements?${params}`;
  const response = await fetch(url, {
    method: "GET",
    headers: { Authorization: `Bearer ${apiToken}` },
  });
  if (!response.ok) throw new Error(`Failed: ${response.status} ${await response.text()}`);
  return response.json();
};

// Usage: first page of titles
getElements("grlm_your_api_token_here", "file_abc123", { page: 1, pageSize: 10, type: "Title" })
  .then((data) => data.items.forEach((el) => console.log(`${el.element_type}: ${el.text}`)))
  .catch(console.error);
```

### Python

```python theme={null}
import requests

def get_elements(api_token, file_id, page=None, page_size=None, suppress_img_base64=False,
                 element_type=None, page_numbers=None, elements_to_remove=None):
    url = "https://sources.graphorlm.com/get-elements"
    headers = {"Authorization": f"Bearer {api_token}"}
    params = {"file_id": file_id}
    if page is not None:
        params["page"] = page
    if page_size is not None:
        params["page_size"] = min(100, max(1, page_size))
    if suppress_img_base64:
        params["suppress_img_base64"] = "true"
    if element_type:
        params["type"] = element_type
    if page_numbers:
        params["page_numbers"] = page_numbers
    if elements_to_remove:
        params["elementsToRemove"] = elements_to_remove

    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    return response.json()

# Usage: tables from pages 2–4
data = get_elements(
    "grlm_your_api_token_here",
    "file_abc123",
    page=1,
    page_size=50,
    element_type="Table",
    page_numbers=[2, 3, 4],
)
for el in data["items"]:
    print(f"Page {el['page_number']}: {el['text'][:100]}...")
```

### cURL

```bash theme={null}
# First page, 10 elements
curl -X GET "https://sources.graphorlm.com/get-elements?file_id=file_abc123&page=1&page_size=10" \
  -H "Authorization: Bearer grlm_your_api_token_here"
```

```bash theme={null}
# Only NarrativeText, exclude images from payload
curl -X GET "https://sources.graphorlm.com/get-elements?file_id=file_abc123&type=NarrativeText&suppress_img_base64=true" \
  -H "Authorization: Bearer grlm_your_api_token_here"
```

```bash theme={null}
# Filter by page numbers and exclude some types
curl -X GET "https://sources.graphorlm.com/get-elements?file_id=file_abc123&page_numbers=1&page_numbers=2&elementsToRemove=PageNumber&elementsToRemove=Footer" \
  -H "Authorization: Bearer grlm_your_api_token_here"
```

## Error responses

| Status code | Description                                  |
| ----------- | -------------------------------------------- |
| `400`       | Invalid input (e.g. missing `file_id`)       |
| `404`       | Source file not found                        |
| `500`       | Internal server error while loading elements |

Example body:

```json theme={null}
{ "detail": "file_id is required" }
```

```json theme={null}
{ "detail": "File not found" }
```

```json theme={null}
{ "detail": "Internal server error occurred while loading file elements" }
```

## Best practices

* **Use `file_id`**: Obtain it from [List sources](/api-reference/sources/list) or [Get build status](/api-reference/sources/upload#get-build-status) after ingestion.
* **Reduce payload**: Set `suppress_img_base64=true` when you don't need image data.
* **Filter server-side**: Use `type`, `page_numbers`, and `elementsToRemove` to limit results.
* **Pagination**: Use `page` and `page_size` (max 100) for large documents to avoid large responses.

## Next steps

<CardGroup cols={2}>
  <Card title="Get build status" icon="circle-info" href="/api-reference/sources/upload#get-build-status">
    Poll build status and optionally get elements for an async ingestion
  </Card>

  <Card title="List sources" icon="list" href="/api-reference/sources/list">
    List all sources and their `file_id`s
  </Card>

  <Card title="Upload sources" icon="arrow-up-from-bracket" href="/api-reference/sources/upload">
    Ingest files, URLs, GitHub, or YouTube (async)
  </Card>

  <Card title="Reprocess source" icon="gears" href="/api-reference/sources/process">
    Re-process a source with a different partition method (async)
  </Card>
</CardGroup>