ScreenshotNeo

BlogHow-to

How to Send GET Requests with cURL: Parameters, Headers, Redirects, and JSON

Learn the correct cURL patterns for GET queries, headers, redirects, JSON responses, authentication, debugging, and safe automation.

By the ScreenshotNeo team30 September 20269 min read

How to Send GET Requests with cURL: Parameters, Headers, Redirects, and JSON

Short answer: cURL sends a GET request when you provide a URL, so the smallest command is curl 'https://api.example.test/items'. Add query parameters with -G and --data-urlencode, headers with one or more -H options, and HTTP redirects with -L. Request a JSON representation with Accept: application/json. Do not use --json for this: cURL documents --json as a shortcut for sending a JSON body with POST.

This guide covers the command patterns you can copy into scripts, how cURL treats encoding and credentials, how to inspect failures, and how to use the same ideas with a screenshot API.

1. Send a basic GET request

Use a quoted URL so shell characters are not interpreted by your shell:

curl 'https://api.example.test/items'

cURL uses GET for a normal URL transfer. You usually do not need -X GET. The -X or --request option changes the literal method string, but it does not change cURL’s underlying behavior. The official cURL man page recommends expressing the operation with the appropriate options instead.

Useful output controls:

# Include response headers
curl -i 'https://api.example.test/items'

# Write only the response body to a file
curl -o items.json 'https://api.example.test/items'

# Follow progress without mixing it into a JSON file
curl -sS -o items.json 'https://api.example.test/items'

# Show the complete request and response exchange for debugging
curl -v 'https://api.example.test/items'

-sS hides the progress meter while keeping error messages. Be careful with -v: verbose output can expose cookies, authorization headers, URLs and other sensitive values in logs.

2. Add query parameters safely

Query parameters belong in the URL after a ?. You can write a short, already encoded query directly:

A GET request combines a URL, optional query parameters and headers before the server returns a response.
A GET request combines a URL, optional query parameters and headers before the server returns a response.
curl 'https://api.example.test/search?q=red%20shoes&page=2'

For scripts, -G (also called --get) is clearer. It tells cURL to put data-option values into the URL query instead of making the request body that those options normally create:

curl -G \
  --data-urlencode 'q=red shoes' \
  --data-urlencode 'page=2' \
  'https://api.example.test/search'

--data-urlencode percent-encodes the value. This matters for spaces, ampersands, question marks, non-ASCII text and JSON-shaped filters. The parameter name itself should already be written as the API expects.

Multiple values and repeated keys

Repeat the option when an API accepts repeated keys:

curl -G \
  --data-urlencode 'tag=red' \
  --data-urlencode 'tag=large' \
  'https://api.example.test/items'

Some APIs instead expect a comma-separated value or bracket notation such as tag[]=red. Follow that API’s contract; cURL does not decide how a server parses repeated parameters.

JSON-shaped data in a query

An endpoint may define a single query parameter that contains JSON text:

curl -G \
  --data-urlencode 'filter={"status":"open","limit":20}' \
  -H 'Accept: application/json' \
  'https://api.example.test/items'

This is still a GET with data in the URL. It is not a JSON request body. Query strings can be recorded in shell history, proxy logs, browser history, monitoring systems and server access logs. Avoid putting passwords, API keys or personal data in them unless the service explicitly requires it and you understand that exposure.

3. Send request headers

Use -H or --header. Repeat it for each header:

curl \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.example.test/items'

Accept describes the response representation you prefer. It does not force a server to return JSON. The server may answer with another media type or an error. Inspect the Content-Type response header with -i or -D -.

# Save response headers separately
curl -sS -D response.headers -o response.body \
  -H 'Accept: application/json' \
  'https://api.example.test/items'

Authentication headers

Bearer authentication is commonly written as:

curl -H "Authorization: Bearer $API_TOKEN" \
  'https://api.example.test/items'

Put the token in an environment variable rather than directly in a command copied into shared history. A basic-auth endpoint can use -u:

curl -u "$API_USER:$API_PASSWORD" \
  'https://api.example.test/items'

Do not print environment variables or include credentials in debug logs. An explicitly supplied Authorization or Cookie header is not normally forwarded by cURL when a redirect changes the host.

Cookies and custom user agents

curl \
  -H 'Cookie: session=YOUR_SESSION' \
  -A 'inventory-check/1.0' \
  'https://api.example.test/items'

Use cookies only when you have permission to access the session. A custom user agent identifies your client; it does not make a request behave like a browser.

4. Follow HTTP redirects

Servers use a 3xx response and a Location header to redirect. cURL does not follow those redirects by default. Add -L or --location:

curl -L --max-redirs 5 \
  'https://api.example.test/items'

--max-redirs sets an explicit ceiling. Choose a limit appropriate to the service and fail rather than loop indefinitely. cURL follows HTTP redirects; it does not execute JavaScript navigation or browser-side HTML meta refresh.

Redirects and secrets

A redirect can move from one origin to another. cURL restricts command-line credentials and explicitly supplied Authorization or Cookie headers to the initial host in normal redirect handling. Avoid --location-trusted unless you deliberately trust every redirect target: it allows sensitive information to be sent to another host and can create a credential leak.

When diagnosing an unexpected redirect, inspect headers without following it:

curl -sS -D - -o /dev/null 'https://api.example.test/items'

5. JSON responses versus JSON request bodies

For a JSON response preference, make a normal GET and set Accept:

curl -H 'Accept: application/json' \
  'https://api.example.test/items'

cURL’s --json option has a different purpose. It sends the supplied data as a POST and sets JSON-related headers. It does not turn a GET into a JSON-body request, and cURL does not validate that the supplied text is valid JSON. The official documentation states: “There is no verification that the passed in data is actual JSON or that the syntax is correct.”

# This is a POST shortcut, not a GET
curl --json '{"status":"open"}' \
  'https://api.example.test/items/search'

If an API claims to accept a body on GET, read that API’s documentation carefully. It is endpoint-specific, and intermediaries may treat GET bodies inconsistently. Prefer query parameters when the API provides them.

6. Complete GET examples in common languages

Shell and cURL

#!/usr/bin/env bash
set -euo pipefail

: "${API_TOKEN:?Set API_TOKEN first}"

curl -sS --fail-with-body -L --max-redirs 5 \
  -G \
  --data-urlencode 'q=red shoes' \
  --data-urlencode 'page=2' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $API_TOKEN" \
  'https://api.example.test/search'

--fail-with-body makes HTTP errors fail while retaining the response body for diagnosis on cURL versions that support it. Check the installed version with curl --version, because option availability varies by release.

Python

import os
import requests

params = {"q": "red shoes", "page": 2}
headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

response = requests.get(
    "https://api.example.test/search",
    params=params,
    headers=headers,
    timeout=30,
    allow_redirects=True,
)
response.raise_for_status()
data = response.json()
print(data)

The requests library encodes the params dictionary and follows redirects by default. Set an explicit timeout in production; without one, a stalled connection can hold a worker indefinitely.

Node.js

const params = new URLSearchParams({ q: 'red shoes', page: '2' });
const response = await fetch(
  `https://api.example.test/search?${params}`,
  {
    headers: {
      Accept: 'application/json',
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
    redirect: 'follow',
  }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data);

Modern Node.js includes fetch. Set an application-level timeout with an AbortController when a request must not wait forever.

7. Troubleshooting common failures

Symptom Likely cause Fix
Server sees POST instead of GET A data option was used without -G. Add -G or place the encoded values in the URL.
Spaces or ampersands break a parameter Shell quoting or URL encoding is missing. Quote the argument and use --data-urlencode.
Only a 301/302 response appears Redirect following is disabled. Use -L; inspect the destination first with -D -.
JSON parsing fails The server returned HTML, plain text or an error document. Inspect Content-Type, status and body before parsing.
401 or 403 Missing, expired or incorrectly formatted credentials; wrong host after redirect. Check the authorization scheme, token scope, URL and redirect target. Never use --location-trusted casually.
Timeout or stalled transfer Network, DNS, TLS or server delay. Set connect and total timeouts, retry only idempotent requests, and capture verbose diagnostics.
Certificate verification error Untrusted or misconfigured TLS certificate. Fix the server certificate or trust store. Avoid disabling verification with -k in production.
Unexpected shell expansion Unquoted &, $, spaces or braces. Use single quotes for fixed literals and --data-urlencode for variables.

For a reproducible bug report, record the cURL version, sanitized command, status code, response headers, redirect chain and a redacted verbose trace. Do not include live tokens, cookies or personal data.

8. Reliability, performance and cost considerations

  • Timeouts: Set a connect timeout and an overall timeout in automation. A command that can wait forever is a reliability risk.
  • Retries: Retry transient DNS, connection and selected 5xx failures with backoff. GET is generally safe to retry because it should be side-effect free, but follow the API’s rate-limit guidance.
  • Redirects: Each redirect adds a request and latency. Keep a maximum and validate that the final host is trusted.
  • Compression: --compressed asks cURL to request compressed content and decompress supported encodings, reducing transfer size when the server supports them.
  • Connection reuse: A single cURL process can reuse connections for multiple transfers, while starting a new process per URL adds setup overhead.
  • Output handling: Stream large bodies to files instead of storing them in shell variables. Check exit status and HTTP status separately.
  • Logging: Query strings and headers may contain secrets. Redact them before storing logs or CI artifacts.

9. Or skip the browser setup with ScreenshotNeo

If your GET workflow is specifically collecting website screenshots, you can call ScreenshotNeo directly instead of maintaining a browser, cookie handling and page-cleanup pipeline. Its API accepts one GET request and returns PNG, JPEG, WebP or PDF output. See the ScreenshotNeo API documentation for the complete parameter list.

A capture service can clean common overlays before returning the page image.
A capture service can clean common overlays before returning the page image.

cURL

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

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const file = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', file);

ScreenshotNeo removes cookie and consent banners, newsletter popups and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

For larger jobs, options include full-page capture with lazy images loaded, CSS-selector element capture, device presets or custom viewports, dark mode, retina scale, custom CSS and JavaScript, clicks, waits, blocked resource types, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call and a usage API. Every feature is on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account to get 1,000 screenshots each month without adding a card.

10. FAQ

Do I need to write -X GET?

No. A normal URL transfer is already GET. Use operation-specific options such as -G for query data.

How do I see the final URL after redirects?

Use -L -w '%{url_effective}\n' and send the body to a file, or inspect each response with verbose output.

Can a GET request contain JSON?

It can contain JSON-shaped text in a query parameter when the API defines that parameter. --json itself sends POST data, so it is not the general solution for a JSON GET.

Why does my API return HTML when I requested JSON?

Check the status code, Content-Type, authentication and redirect destination. Accept: application/json expresses a preference; the server still controls the response.

How can I prevent credentials crossing a redirect?

Use normal -L behavior, limit redirects with --max-redirs, and verify the destination host. Do not use --location-trusted unless every target is trusted.