---
title: "A client PDF's state and download link"
method: GET
path: "/v1/search/pdfs/{pdf_id}"
tags: ["gsc"]
---

# A client PDF's state and download link

`GET /v1/search/pdfs/{pdf_id}`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/search/pdfs/{pdf_id}`
- Auth: HTTP bearer

One client PDF: its `period`, `sections`, `state` and the state's `sentence` (what a waiting PDF waits for and when Frontshelf tries again, why a failed one failed, when and why a withdrawn one was withdrawn), and on a ready PDF `download_url`, a signed link good for 15 minutes with no Authorization header: hand it to your human, never anywhere else. A withdrawn (invalidated) PDF has no link: the data it held was erased. A PDF that is not this workspace's, or is on a site this key cannot see, is NOT_FOUND.

## Path parameters

- `pdf_id` string, required: The PDF's id (spdf_…), from gsc_pdfs_request.

## Response `200`

A client PDF's state and download link

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `id` string, required: The PDF's id (spdf_…): what gsc_pdfs_get takes.
  - `site_id` string, required: The site's canonical id.
  - `period` object, required: The Pacific days it covers.
    - `start` string, required
    - `end` string, required
  - `sections` string[], required
  - `state` 'queued' | 'building' | 'waiting' | 'ready' | 'failed' | 'invalidated', required: queued or building (the renderer makes it), waiting (a prerequisite that can return), ready, failed, or invalidated (withdrawn: data it held was erased).
  - `reason` 'no_blob_store' | 'not_final' | 'not_connected' | 'gated' | 'render_failed' | 'store_failed' | 'expired' | 'source_erased' | 'analytics_erased': Why it waits, failed or was withdrawn.
  - `next_try_at` string: A waiting PDF: when Frontshelf tries again.
  - `ready_at` string: An instant, ISO 8601.
  - `bytes` integer: A ready PDF's size.
  - `at` string: A withdrawn PDF: when it was withdrawn.
  - `sentence` string, nullable, required: The state in words: what a waiting PDF waits for and when it tries again, why one failed, when and why one was withdrawn; null for queued, building and ready.
  - `download_url` string, nullable, required: A ready PDF's signed download link, good for 15 minutes with no Authorization header; null in every other state. A secret: hand it to your human, never anywhere else.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: NOT_FOUND
- `409`: AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)