LambdaTest Screenshot API Authentication and API Key Setup
Set up LambdaTest Screenshot API credentials and HTTP Basic authentication, then troubleshoot common request failures with runnable examples.
To authenticate with the LambdaTest Automated Screenshot API, use your LambdaTest account username and access key as HTTP Basic credentials. Send a JSON POST request to https://api.lambdatest.com/screenshots/v1/; a successful start request returns a test_id.
In the Basic credentials pair, the username is your account username and the password is your access key. Keep both values private. LambdaTest documents LT_USERNAME and LT_ACCESS_KEY as environment variable names for command-line setup. See the official Automated Screenshot API setup guide and Start Screenshot Test API reference.
1. Get your username and access key
- Sign in to the LambdaTest automation dashboard.
- Find the account username and access key in the dashboard’s key control near the help button.
- Store them in environment variables or a secret store used by your application. Do not put real credentials in source code, public examples, or version control.
The API reference defines the authorization header as Basic followed by the base64-encoded value of username:password. For this account-credential setup, use the access key as the password value. Base64 is encoding, not encryption, so send the header only over HTTPS and do not log it.
2. Configure the credentials
Linux and macOS
export LT_USERNAME='your-lambdatest-username'
export LT_ACCESS_KEY='your-lambdatest-access-key'These values are available to processes launched from that shell. For a persistent or deployed application, configure them through the environment or secret-management facility used by your runtime.
Windows Command Prompt
set LT_USERNAME=your-lambdatest-username
set LT_ACCESS_KEY=your-lambdatest-access-keyThese commands set the variables for the current Command Prompt session. In PowerShell, the equivalent for the current session is:
$env:LT_USERNAME = 'your-lambdatest-username'
$env:LT_ACCESS_KEY = 'your-lambdatest-access-key'3. Send an authenticated request
The start operation accepts a JSON body. This minimal example follows the documented request shape and asks LambdaTest to capture https://example.com:
cURL
curl --request POST \\
--url 'https://api.lambdatest.com/screenshots/v1/' \\
--user "$LT_USERNAME:$LT_ACCESS_KEY" \\
--header 'Content-Type: application/json' \\
--data '{"url":"https://example.com","defer_time":0,"email":true,"configs":{}}'cURL’s --user option constructs HTTP Basic authentication from the username and access key. If you need to construct the header yourself, the value after Basic must be the base64 encoding of the exact byte sequence username:access-key; do not include angle brackets or a newline. The request should still be sent over HTTPS.
Python
import os
import requests
username = os.environ["LT_USERNAME"]
access_key = os.environ["LT_ACCESS_KEY"]
response = requests.post(
"https://api.lambdatest.com/screenshots/v1/",
auth=(username, access_key),
headers={"Content-Type": "application/json"},
json={
"url": "https://example.com",
"defer_time": 0,
"email": True,
"configs": {},
},
timeout=60,
)
response.raise_for_status()
print(response.json())Install the dependency with python -m pip install requests. The timeout is a client-side safeguard; choose a value appropriate for your application. Inspect the JSON response for the returned test_id.
Node.js
const username = process.env.LT_USERNAME;
const accessKey = process.env.LT_ACCESS_KEY;
if (!username || !accessKey) {
throw new Error('Set LT_USERNAME and LT_ACCESS_KEY first');
}
const credentials = Buffer.from(`${username}:${accessKey}`).toString('base64');
const response = await fetch('https://api.lambdatest.com/screenshots/v1/', {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://example.com',
defer_time: 0,
email: true,
configs: {},
}),
signal: AbortSignal.timeout(60000),
});
if (!response.ok) {
throw new Error(`LambdaTest request failed: HTTP ${response.status} ${await response.text()}`);
}
console.log(await response.json());This uses the Node.js global fetch and Buffer. If your runtime does not provide global fetch or AbortSignal.timeout, use the HTTP client and timeout mechanism supported by that runtime.
4. Understand the response
A successful start operation returns a test_id identifying the screenshot test. Save it if your workflow needs to retrieve or track the test later. The start operation reference includes response examples for HTTP 200, 400, 401, and 403. It does not, on the retrieved page, assign a definitive cause to each authentication-related status, so use the returned response details and verify the request inputs rather than assuming a particular cause.
Authentication checklist
- Use the LambdaTest automation account username, not an email address unless that is actually the username shown for your account.
- Use the access key as the Basic authentication password.
- Send
POSTto the documented HTTPS endpoint:https://api.lambdatest.com/screenshots/v1/. - Send JSON with
Content-Type: application/json. - Keep credentials outside source code and avoid printing the Authorization header.
- Retain the returned
test_idfor follow-up in your screenshot workflow.
Options and request details
The start-test request is JSON. The documented example shape includes a capture URL, defer_time, email, and configs. The API reference says the body can include browser and operating-system configurations, resolutions, and other test options. This article focuses on authentication; consult the current operation reference for the accepted fields and their precise values before adding configuration. Do not assume that an authentication example documents every capture option.
For a reliable request, ensure the target URL is an absolute URL with a scheme such as https://, serialize the body as valid JSON, and handle non-success HTTP responses before parsing a success payload. Keep the access key out of request-body fields: it belongs in the Basic Authorization header.
Troubleshooting
| Symptom | What to check | Fix |
|---|---|---|
| HTTP 401 | The credentials, Basic scheme, and encoded username/access-key pair. | Confirm both values against the automation dashboard, ensure the access key is used as the password, and retry with a correctly formed Basic header. The API reference lists a 401 response but does not establish a more specific cause. |
| HTTP 403 | Whether the request is reaching the documented endpoint with the intended account credentials. | Review the response body and account setup, then verify the endpoint, method, and authentication. The reference shows a 403 example but does not specify its cause. |
| HTTP 400 | JSON syntax, required request fields, URL format, and option names. | Send valid JSON with the capture URL and check the current start-test reference for supported fields. A 400 is listed in the reference; the exact cause depends on the response and request. |
| Missing environment variable | Whether the application was started from a shell or deployment environment containing both variables. | Set LT_USERNAME and LT_ACCESS_KEY in the process environment, then restart the application. |
| Malformed Authorization header | The exact credential pair and encoding. | Use an HTTP client’s Basic-auth support, such as cURL --user or Python Requests auth=(username, access_key). When building it manually, encode username:access-key once and prefix with Basic . |
| Request appears to hang | Client timeout and network connectivity to the HTTPS API host. | Set a client-side timeout, surface timeout errors distinctly, and retry only according to your application’s retry policy. A timeout does not establish whether the remote operation started; avoid blindly launching duplicate captures. |
| Cannot parse response as JSON | Whether the HTTP request succeeded and whether the response body is JSON. | Check the status and read the response body as text for errors before parsing it as a successful JSON result. |
Security, reliability, and cost considerations
Protect the key
- Do not commit access keys or paste them into tickets, logs, or client-side code.
- Use HTTPS and limit access to the environment or secret store that holds the key.
- Do not log the complete Basic Authorization header: it can be decoded to reveal both credential values.
- If a key is exposed, use the account’s credential controls to address the exposure and update the deployed secret.
Make requests resilient
Set a client timeout and report the HTTP status and safe response details when a call fails. Retry transient network failures cautiously and avoid logging credentials. Since a client timeout can occur after the server has received a request, check the operation state and preserve any known test_id before resubmitting, where your workflow allows it. The cited start-test reference documents the returned identifier but does not describe retry or idempotency guarantees.
Plan for request and capture costs
Authentication itself does not describe the account’s pricing or the cost of a particular capture. Check your LambdaTest plan and current billing terms before running large batches; the cited authentication pages do not establish prices or a billing model. Use only the browser and operating-system configurations your test needs, and retain the test_id so your workflow can associate results with the request.
Or skip the browser setup
If your goal is a clean image or PDF from a URL rather than a LambdaTest cross-browser test run, ScreenshotNeo offers a direct screenshot API and an MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. AI agents can use its MCP server tools: take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for options and request details. For example, this cURL request saves a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; yearly billing gives two months free, and every feature is available on every plan. Sign up for ScreenshotNeo and get 1,000 screenshots a month free, with no card.
FAQ
Is the LambdaTest access key the Basic-auth password?
Yes. For this API account-credential setup, send the account username as the Basic username and the access key as its password value.
Does the API key go in the JSON body?
No. The documented authentication method is HTTP Basic authentication in the Authorization header.
What should I save from a successful start request?
Save the returned test_id, which identifies the screenshot test.
Does HTTP 401 tell me exactly what is wrong?
The operation reference includes a 401 response example, but the retrieved reference does not map it to one exact cause. Check the credentials and header first, then inspect the response body.
