AlterLabHTTP Methods & Request Bodies
Go beyond GET scraping. Use AlterLab as a proxy for GraphQL queries and HTML form submissions — with the same anti-bot protections and response parsing you rely on for standard scraping.
Milestone feature
method, body, and content_type parameters are part of the HTTP Method & Body Support milestone. They are available in the current API version.When to Use POST
Standard scraping is a GET request — you fetch a URL and get HTML back. That covers most public pages. But many data sources expose their content only through POST requests:
GraphQL Endpoints
GraphQL APIs require a POST with a JSON body containing your query. The endpoint is a single URL and all data selection happens in the body.
Form Submissions
Some sites return dynamic content only after a form POST — search results, login-gated content, or multi-step flows that carry state in form fields.
JSON APIs
Many internal or undocumented APIs serve data as JSON in response to a POST. AlterLab can relay the request and return the raw JSON response.
Webhook Triggers
Some endpoints accept a bodyless POST to trigger an action and return data. AlterLab supports POST with or without a body.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| method | GET | POST | GET | HTTP method to use when fetching the target URL. Default is GET (standard page scrape). |
| body | string | null | Request body to send. Must be a UTF-8 string. Maximum 1 MB (10 MB for high-volume/enterprise tiers). Cannot be used with method=GET. |
| content_type | string | application/json | Content-Type header for the body. Supported: application/json, application/x-www-form-urlencoded, text/plain. Ignored when body is not set. |
GraphQL Use Case
GraphQL APIs accept a POST request with a JSON body containing a query field (and optional variables). Set method=POST and pass the query as a JSON string in body.
curl -X POST https://api.alterlab.io/api/v1/scrape \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://countries.trevorblades.com/graphql",
"method": "POST",
"body": "{\"query\": \"{ countries { name capital currency } }\"}",
"content_type": "application/json"
}'GraphQL with variables
variables field in your JSON body for parameterized queries:{
"query": "query GetCountry($code: ID!) { country(code: $code) { name capital } }",
"variables": { "code": "US" }
}Form Submission Use Case
To simulate an HTML form submission, set content_type=application/x-www-form-urlencoded and encode your form fields in the body as key=value&key2=value2.
curl -X POST https://api.alterlab.io/api/v1/scrape \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/search",
"method": "POST",
"body": "q=web+scraping+api&category=tools&page=1",
"content_type": "application/x-www-form-urlencoded"
}'Form authentication flows
method=POST with the Authenticated Scraping guide.Decision Guide
Use this table to pick the right method and content type for your use case:
| Goal | method | content_type | Body format |
|---|---|---|---|
| Scrape a standard web page | GET | — (omit) | — (omit) |
| GraphQL query | POST | application/json | {"query": "...", "variables": {}} |
| HTML form submission | POST | application/x-www-form-urlencoded | key=value&key2=val2 |
| POST to a JSON REST API | POST | application/json | JSON string |
Constraints & Limits
Body size limit: 1 MB (10 MB for enterprise)
The body field accepts up to 1 MB (1,048,576 bytes) for standard tiers, and up to 10 MB (10,485,760 bytes) for high-volume and enterprise tiers. This covers all standard GraphQL queries, form payloads, and REST request bodies.
Body cannot be used with GET
Providing a body when method=GET returns a 400 Bad Request. Use method=POST if you need to send a body.
Caching is disabled for non-GET methods
The cache parameter is ignored when method is not GET. Non-idempotent requests are never cached.
UTF-8 strings only
The body field must be a valid UTF-8 string. Binary payloads are not supported. For binary data, encode as base64 if the target API accepts it.
Troubleshooting
GraphQL returns an error response instead of data
- Ensure
bodyis a valid JSON string (not a raw object). UseJSON.stringify()orjson.dumps(). - Check that
content_typeisapplication/json. Some GraphQL servers reject requests without this header. - If the endpoint requires authentication, combine with the Authenticated Scraping guide to pass session cookies.
Form submission returns the login page instead of results
The server may expect a CSRF token in the form body. Fetch the page first with a GET request to extract the token, then replay the POST with the token included in your form body.
400 error: body cannot be used with GET method
You have set a body field while method is GET (or omitted, since GET is the default). Set method to POST or another appropriate value.
Response is HTML instead of JSON
If the target API redirects to a login page or error page, the content field will contain HTML rather than JSON. Check the HTTP status in the response metadata and verify the endpoint URL and authentication requirements.