POST /v1/snapshot/queue

Queue one or more page paths for rendering or re-rendering. Use this endpoint after publishing new content, launching new pages, or pre-warming your snapshot cache before a marketing campaign. Queued pages are processed by PerfectSearch rendering workers and snapshots become available within seconds.

How do I queue pages for rendering?

Send a POST request to /api/v1/snapshot/queue with a JSON body containing your site ID and an array of URL paths to render. The API returns a count of successfully queued jobs along with their job IDs. Use this endpoint after publishing new content or to pre-warm your snapshot cache so bots never encounter a cache miss.

curl -X POST \
  -H "Authorization: Bearer ps_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "site_abc123",
    "paths": ["/products/new-shoe", "/collections/summer"],
    "priority": "high"
  }' \
  https://search.perfectline.io/api/v1/snapshot/queue

What is the request body?

The request body must be valid JSON with the Content-Type: application/json header set. The siteId and paths fields are required. Each path must start with a forward slash and represent a valid URL path on your site.

Example request body:

{
  "siteId": "site_abc123",
  "paths": ["/products/new-shoe", "/collections/summer"],
  "priority": "high"
}

What does the response look like?

A successful response returns HTTP 200 with a JSON body containing the number of jobs queued and an array of job IDs. Each job ID corresponds to a single path in the request. You can use these job IDs to track rendering progress in the dashboard or via future API endpoints. If a path already has a fresh snapshot, it is still re-queued and will overwrite the existing snapshot when rendering completes.

{
  "queued": 2,
  "jobIds": ["job_abc123", "job_def456"]
}

The queued count matches the number of paths submitted. Each path generates exactly one rendering job, and each job produces both an HTML and Markdown snapshot for the page.

How long does rendering take?

Rendering typically takes 5 to 30 seconds per page, depending on page complexity, the number of external resources loaded (fonts, images, third-party scripts), and current queue depth. High priority jobs are dequeued before normal priority jobs, so they complete faster when the queue is busy. Simple static pages render in under 10 seconds, while heavy single-page applications with client-side data fetching may take up to 30 seconds.

Is there a limit on how many paths I can queue?

Each request can contain a maximum of 100 paths. If you need to queue more than 100 pages, split them into multiple requests. There is no limit on the total number of requests you can make (beyond your plan's rate limit), so you can queue thousands of pages by batching them into groups of 100. Paths that are already being rendered are deduplicated automatically — submitting the same path twice does not create a duplicate job.

// Queue 500 pages in batches of 100
const allPaths = generatePaths(); // string[]

for (let i = 0; i < allPaths.length; i += 100) {
  const batch = allPaths.slice(i, i + 100);
  await fetch('https://search.perfectline.io/api/v1/snapshot/queue', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ps_live_abc123def456',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      siteId: 'site_abc123',
      paths: batch,
      priority: 'normal',
    }),
  });
}