Fix Browshot Screenshot Jobs Stuck in Processing

If a Browshot screenshot stays in processing, query its screenshot ID with /api/v1/screenshot/info, then request details=1 and inspect the returned status and diagnostic fields. Browshot documents in_queue, processing, finished, and error as the job states. Its guidance is to keep checking until the job reaches finished or error. The documentation does not define a universal processing timeout or a manual reset for an individual job, so a status check can clarify what is known without guaranteeing a particular fix. Browshot API documentation

1. Check the screenshot ID and current status

Use the ID returned when you created the screenshot. Query the information endpoint and record the status and any timestamp fields it returns. These examples use the documented endpoint and a placeholder for your Browshot API key; consult your account’s current API instructions for authentication details.

curl -G 'https://api.browshot.com/api/v1/screenshot/info' \
  --data-urlencode 'id=SCREENSHOT_ID' \
  --data-urlencode 'key=YOUR_BROWSHOT_API_KEY'

A minimal Python request:

import requests

response = requests.get(
    "https://api.browshot.com/api/v1/screenshot/info",
    params={"id": "SCREENSHOT_ID", "key": "YOUR_BROWSHOT_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

A minimal Node.js request:

const params = new URLSearchParams({
  id: 'SCREENSHOT_ID',
  key: 'YOUR_BROWSHOT_API_KEY',
});

const response = await fetch(
  `https://api.browshot.com/api/v1/screenshot/info?${params}`
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

in_queue: the request is waiting in the queue according to the state name.
processing: the job has not reached either documented terminal state yet.
finished: the screenshot job completed.
error: the job ended in an error; inspect details for an explanation where available.

Keep polling at a measured interval rather than issuing a tight loop. The docs direct clients to check until finished or error, but do not specify a universal maximum duration or recommended polling interval.

2. Ask for diagnostic details

Add details=1 to the information request. Browshot documents that the detailed response can include an error description and final URL information. Compare the requested URL with final_url or final_urls when present; redirects may mean the browser reached a different address than the one submitted.

curl -G 'https://api.browshot.com/api/v1/screenshot/info' \
  --data-urlencode 'id=SCREENSHOT_ID' \
  --data-urlencode 'key=YOUR_BROWSHOT_API_KEY' \
  --data-urlencode 'details=1'

Record the response as returned. If there is no error description, do not infer a cause from the processing label alone. Where the response includes response-code or timing fields, include those in your investigation as well.

3. Determine whether one job or many are affected

Use Browshot’s screenshot list endpoint to inspect recent requests and filter by status, or its search endpoint to find requests matching a URL. The documented views return a maximum of 100 results. A single job behaving differently from other jobs can help narrow the investigation, but list results by themselves do not prove that the service is or is not experiencing an incident.

# Recent requests (add supported filters as needed)
curl -G 'https://api.browshot.com/api/v1/screenshot/list' \
  --data-urlencode 'key=YOUR_BROWSHOT_API_KEY'

# Requests matching a URL
curl -G 'https://api.browshot.com/api/v1/screenshot/search' \
  --data-urlencode 'key=YOUR_BROWSHOT_API_KEY' \
  --data-urlencode 'url=https://example.com/'

Use the exact parameter names and authentication format documented for your API host when adding a status filter or other search options. Keep the result limit in mind when comparing a large set of requests.

4. Review request settings that affect elapsed time or reuse

Check the original create request and its parameters. These settings can affect how long a request appears to take or whether a result is reused; their presence does not establish the cause of a specific job’s processing state.

Setting	What to check	Diagnostic note
`delay`	How long the request waits after the page loads before capture.	The API documentation gives a 5-second default. Documented bounds differ across documentation versions or regions, so verify the range for the API host you use.
`max_wait`	How long the request waits for the PageLoad event.	The documented default is disabled (`0`); the documentation describes a maximum of 60 seconds.
`cache`	Whether a previous screenshot for the same URL and instance may be reused.	The documentation describes a 24-hour default and `cache=0` for requesting a fresh capture. A cached result can look stale, but does not by itself explain a job’s status.

Do not copy a parameter range from a different Browshot documentation host without checking that it applies to your host and version.

5. Check service status and prepare an escalation

Browshot’s API documentation points to its extended status page for service availability updates. Check it for current information; an individual job’s status cannot establish whether there is a service incident.

If the job remains in processing, collect this evidence before contacting support:

Screenshot ID and requested URL.
Instance and request or creation time.
The status and timestamp fields from repeated information checks.
The full details=1 response, including final URL and error fields if returned.
Whether other recent jobs or jobs for the same URL show similar behavior.
The relevant original request settings, including delay, max_wait, and cache.

This is a practical evidence checklist, not a documented mandatory support procedure. Do not claim a root cause unless the response or Browshot confirms one.

6. Use hooks for future jobs, with status polling as a fallback

Browshot supports a hook URL that receives a POST when a screenshot reaches finished or error. The callback body is described as the screenshot information JSON. Browshot documents up to two retries if the callback is slow or fails to return a 20X response.

Use the callback to update your application promptly, and retain a way to query screenshot/info if a notification is delayed or missed. The callback retry behavior does not make a callback a substitute for being able to inspect the job’s state.

Common problems and fixes

Symptom	Likely explanation or limit	What to do
The response says `in_queue`.	The job has not begun processing according to the state label.	Keep checking the same screenshot ID and compare recent jobs. The docs do not specify a universal queue wait limit.
The response still says `processing`.	The job has not reached a documented terminal state. The status alone does not identify why.	Request `details=1`, record timestamps, compare other jobs, and check the status page.
The job says `error`, but the cause is unclear.	The basic response may omit diagnostic information.	Request `details=1` and inspect the error description and final URL fields when present.
The screenshot looks outdated.	A prior capture may have been reused through caching.	Review the original cache setting; Browshot documents `cache=0` for a fresh request.
Your callback did not update the application.	The callback may be delayed, fail to return a 20X response, or exhaust the documented retries.	Check the receiver’s logs and response behavior, and query screenshot info for the authoritative current job state.
List or search appears incomplete.	The documented result limit is 100.	Narrow the query by status or URL and inspect a smaller relevant set.
One URL fails while others complete.	The comparison suggests a URL-specific difference, but does not prove its cause.	Inspect detailed fields and redirects for that job; include the URL and evidence when escalating.

Performance, reliability, and cost considerations

For an application that submits many jobs, avoid a rapid polling loop: it creates needless API traffic and still cannot make a screenshot finish sooner. A hook can reduce routine polling, while periodic status checks provide a recovery path for missed callbacks. The documented up-to-two callback retries are not a guarantee that every notification reaches your application.

Account balance can affect whether requests to private and shared instances can be made: Browshot documents that these requests require a positive balance. Check the account and instance requirements if a new request cannot be submitted. A balance requirement does not explain an already-created job’s processing status. The reviewed documentation does not provide a universal processing-time promise, so avoid building a fixed timeout assumption from one job.

Or skip the browser setup

If your task is to get a screenshot rather than diagnose an existing Browshot job, ScreenshotNeo is a website screenshot API and MCP server for developers. Its single GET endpoint returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account.

FAQ

Can I manually reset a Browshot job that is processing?

The reviewed API documentation does not describe a manual reset for an individual job. Check its detailed status and contact Browshot with the job evidence if it remains unresolved.

How long should I wait before escalating?

Browshot does not document one universal processing timeout. Record the status over time, compare other jobs, and use the status page and support evidence rather than assuming a fixed cutoff.

Does a processing status mean Browshot is down?

No. A single job’s state does not establish an outage. Check the official status page and compare other requests.

Will setting `max_wait` fix a job already stuck in processing?

It is a request setting related to waiting for the PageLoad event. The documentation does not say changing it will repair an existing job or explain a particular processing delay.