Get page screenshot - Graphor Docs

The get_page_screenshot method renders one page of a source file (PDF, image, or Office document) as a base64-encoded PNG. It is the recommended way to display visual previews for citations returned by ask — call it lazily, only when the user actually wants to inspect a citation.

Method overview

Python
TypeScript

Sync Method

client.sources.get_page_screenshot()

Async Method

await client.sources.get_page_screenshot() (using AsyncGraphor)

Async Method

await client.sources.getPageScreenshot()All TypeScript methods are async and return a Promise.

Method signature

Python
TypeScript

client.sources.get_page_screenshot(
    page_number: int,                     # Required (path)
    file_id: str,                         # Required
    max_width: int | None = None,
    timeout: float | None = None
) -> SourceGetPageScreenshotResponse

await client.sources.getPageScreenshot(
  pageNumber: number,                     // Required (path)
  params: {
    file_id: string,                      // Required
    max_width?: number | null,
  },
): Promise<SourceGetPageScreenshotResponse>

Parameters

Python
TypeScript

Parameter	Type	Description	Required
`page_number`	`int`	1-based page number. For image-type files, must be `1`.	Yes
`file_id`	`str`	UUID of the source file. Same value returned in `citations[].file_id` from `ask`.	Yes
`max_width`	`int \| None`	Pixel width cap. Clamped to `300`-`1600`. Default: `900`.	No
`timeout`	`float`	Request timeout in seconds	No

Parameter	Type	Description	Required
`pageNumber`	`number`	1-based page number. For image-type files, must be `1`.	Yes
`file_id`	`string`	UUID of the source file.	Yes
`max_width`	`number \| null`	Pixel width cap. Clamped to `300`-`1600`. Default: `900`.	No

Supported file types

Type	Extensions	Notes
PDFs	`pdf`	Any 1-based page number.
Images	`png`, `jpg`, `jpeg`, `webp`, `gif`, etc.	`page_number` must be `1`.
Office documents	`doc`, `docx`, `ppt`, `pptx`, `odt`	Rendered from the auto-converted PDF.

Plain-text and other non-visual formats are not supported and will raise NotFoundError.

Response

Property	Type	Description
`file_id`	`str`	UUID of the source file.
`file_name`	`str \| None`	Display name of the source file.
`page_number`	`int`	1-based page number that was rendered.
`mime_type`	`str`	MIME type of the encoded image (always `"image/png"`).
`width`	`int \| None`	Pixel width of the rendered image.
`height`	`int \| None`	Pixel height of the rendered image.
`image_base64`	`str`	Base64-encoded PNG image bytes.

Code examples

Basic — render and save a page

Python
TypeScript

import base64
from graphor import Graphor

client = Graphor()

screenshot = client.sources.get_page_screenshot(
    page_number=42,
    file_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

png_bytes = base64.b64decode(screenshot.image_base64)
with open("page-42.png", "wb") as f:
    f.write(png_bytes)

print(f"Rendered {screenshot.width}x{screenshot.height} PNG")

import fs from 'node:fs/promises';
import Graphor from 'graphor';

const client = new Graphor();

const screenshot = await client.sources.getPageScreenshot(42, {
  file_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
});

await fs.writeFile('page-42.png', Buffer.from(screenshot.image_base64, 'base64'));

console.log(`Rendered ${screenshot.width}x${screenshot.height} PNG`);

Lazy-loading citations from `ask`

The recommended pattern: call ask, render only the pages the user inspects.

Python
TypeScript

from graphor import Graphor

client = Graphor()

response = client.sources.ask(
    question="What was the revenue in 2025?",
    file_ids=["file_abc123"],
)

print(response.answer)

# When the user hovers/clicks on a [N] marker, fetch the screenshot
def fetch_citation_image(citation):
    return client.sources.get_page_screenshot(
        page_number=citation.page_number,
        file_id=citation.file_id,
        max_width=500,  # smaller for tooltip/popover
    )

# Example: render only the first cited page
if response.citations:
    screenshot = fetch_citation_image(response.citations[0])
    # screenshot.image_base64 → display in <img src="data:image/png;base64,...">

import Graphor from 'graphor';

const client = new Graphor();

const response = await client.sources.ask({
  question: 'What was the revenue in 2025?',
  file_ids: ['file_abc123'],
});

console.log(response.answer);

// When the user hovers/clicks on a [N] marker, fetch the screenshot
async function fetchCitationImage(citation: { file_id: string; page_number: number }) {
  return client.sources.getPageScreenshot(citation.page_number, {
    file_id: citation.file_id,
    max_width: 500, // smaller for tooltip/popover
  });
}

if (response.citations?.length) {
  const screenshot = await fetchCitationImage({
    file_id: response.citations[0].file_id!,
    page_number: response.citations[0].page_number!,
  });
  // screenshot.image_base64 → display via `data:image/png;base64,${...}`
}

Async usage

Python
TypeScript

import asyncio
from graphor import AsyncGraphor

async def render_pages(file_id: str, pages: list[int]):
    client = AsyncGraphor()
    results = await asyncio.gather(*[
        client.sources.get_page_screenshot(page_number=p, file_id=file_id)
        for p in pages
    ])
    return [r.image_base64 for r in results]

asyncio.run(render_pages("file_abc123", [1, 2, 3]))

import Graphor from 'graphor';

const client = new Graphor();

async function renderPages(fileId: string, pages: number[]) {
  const results = await Promise.all(
    pages.map((p) =>
      client.sources.getPageScreenshot(p, { file_id: fileId }),
    ),
  );
  return results.map((r) => r.image_base64);
}

await renderPages('file_abc123', [1, 2, 3]);

Best practices

Lazy-load on user interaction — call this method only when the user hovers, clicks, or expands a citation. Most citations are never inspected.
Cache by (file_id, page_number) — the response is deterministic for a given key. Cache the base64 string in memory for the duration of the session to avoid re-rendering.
Pick max_width for the surface you’re rendering — 500 for tooltips/popovers, 900 (default) for inline cards, 1200+ only when the user opens a full preview.
Prefer this over include_citation_images=True in ask — embedding base64 inline bloats the JSON payload by hundreds of KB per cited page and runs all renders synchronously before the answer returns. See When to use include_citation_images.

Error handling

Python
TypeScript

import graphor
from graphor import Graphor

client = Graphor()

try:
    screenshot = client.sources.get_page_screenshot(
        page_number=42,
        file_id="file_abc123",
    )
except graphor.NotFoundError:
    # File not found, unsupported file type, or invalid page number
    screenshot = None
except graphor.AuthenticationError as e:
    print(f"Invalid API key: {e}")
except graphor.APIStatusError as e:
    print(f"API error (status {e.status_code}): {e}")

import Graphor from 'graphor';

const client = new Graphor();

try {
  const screenshot = await client.sources.getPageScreenshot(42, {
    file_id: 'file_abc123',
  });
} catch (err) {
  if (err instanceof Graphor.NotFoundError) {
    // File not found, unsupported file type, or invalid page number
  } else if (err instanceof Graphor.AuthenticationError) {
    console.log(`Invalid API key: ${err.message}`);
  } else if (err instanceof Graphor.APIError) {
    console.log(`API error (status ${err.status}): ${err.message}`);
  } else {
    throw err;
  }
}

Chat

Ask questions and receive grounded answers with citations

List Sources

Discover the file_id values you can pass here

​Method overview

Sync Method

Async Method

Async Method

​Method signature

​Parameters

​Supported file types

​Response

​Code examples

​Basic — render and save a page

​Lazy-loading citations from ask

​Async usage

​Best practices

​Error handling

​Related

Chat

List Sources

Method overview

Method signature

Parameters

Supported file types

Response

Code examples

Basic — render and save a page

Lazy-loading citations from `ask`

Async usage

Best practices

Error handling

Related