Documentação do ScraperFly
Início rápido: autentique-se com sua chave de API, busque HTML, ative a renderização de JS, escolha formatos de saída e use proxies premium. O ScraperFly é intencionalmente direto: envie uma URL, escolha os controles que você precisa e manipule o HTML retornado, texto limpo, Markdown, JSON, captura de tela ou PDF em sua aplicação.
/api/v1
Use parâmetros de consulta GET ou JSON POST. Ambas as formas de solicitação retornam o mesmo resultado.
apikey cabeçalho
Mantenha as chaves no lado do servidor e gire-as a partir do painel sempre que necessário.
1 a 25 créditos
Os custos dependem do roteamento premium, renderização de navegador e saída de arquivo visual.
Custos de Crédito & Solicitações Falhadas
Os créditos dependem da configuração da solicitação (proxies premium, renderização de JS, etc.) e do resultado final. Na prática, cada solicitação custa entre 1 e 25 créditos.
| Premium | Renderizar | Custo em créditos |
|---|---|---|
| false | false | 1 |
| false | true | 5 |
| true | false | 10 |
| true | true | 25 |
- Comece com
premium=false,render=falsepara alvos fáceis. - Ative
render=trueapenas para páginas pesadas em JS (React/Vue/Next.js). - Use
countryquando o alvo mudar por localização. - Se você encontrar páginas de desafio, tente
premium=true+render=true.
Uso Básico
Busque o HTML de uma página de destino. Para uso básico, você só precisa de sua apikey e uma url. Isso normalmente usa proxies padrão e custa 1 crédito. A resposta é o HTML bruto da página. Se você precisar de dados estruturados, analise o HTML do seu lado (Cheerio/BeautifulSoup/etc.).
curl "https://scraperfly.com/api/v1?url=https://example.com" \
-H "apikey: YOUR_API_KEY_HERE"
// Node 18+ tem fetch embutido
const res = await fetch("https://scraperfly.com/api/v1?url=https://example.com", {
headers: { apikey: "YOUR_API_KEY_HERE" }
});
const html = await res.text();
console.log(html);
import requests
res = requests.get(
"https://scraperfly.com/api/v1",
params={"url": "https://example.com"},
headers={"apikey": "YOUR_API_KEY_HERE"}
)
print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$url = "https://example.com";
$ch = curl_init($endpoint . "?url=" . urlencode($url));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
endpoint := "https://scraperfly.com/api/v1?url=" + url.QueryEscape("https://example.com")
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
var endpoint = "https://scraperfly.com/api/v1?url=https://example.com";
var html = await http.GetStringAsync(endpoint);
Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com"))
.header("apikey", "YOUR_API_KEY_HERE")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.request(req)
end
puts res.body
Parâmetros de Solicitação
Use o ponto de extremidade canônico GET /api/v1 com parâmetros de consulta, ou POST /api/v1 com os mesmos campos em um corpo JSON. Comece com url + format, depois adicione opções de proxy, renderização, viewport ou arquivo apenas quando o alvo precisar deles.
Solicitação principal
| Parâmetro | Tipo | Descrição |
|---|---|---|
url | obrigatório | URL do site alvo que você deseja raspar, por exemplo url=https://example.com. |
premium | opcional, booleano | Usa pools de proxy de maior qualidade para alvos mais difíceis. Custa mais créditos. |
country | opcional | País do proxy solicitado, por exemplo US. Os logs de uso armazenam o país e a cidade reais do proxy. |
render | opcional, booleano | Renderização de navegador headless para páginas que requerem JavaScript. Ativado automaticamente para screenshot e pdf. |
keep_headers | opcional, booleano | Transfira seus próprios cabeçalhos (cookies, user-agent, accept-language, etc.). |
format | opcional | Formato de saída: html, text, markdown, json, screenshot, ou pdf. |
Formatos de saída
| formato | Resposta | Quando usar |
|---|---|---|
html | HTML | Padrão. Use quando você quiser a fonte bruta ou HTML renderizado para seu próprio parser. |
text | texto simples | Use quando você precisar de texto limpo e legível sem ruído de navegação/layout. |
markdown | Markdown | Use para prompts LLM, RAG, docs, resumos e indexação. |
json | JSON | Use para metadados, título, cabeçalhos, links, texto limpo e Markdown em uma única resposta. |
screenshot | arquivo de imagem | Sempre usa Chromium. Use para prova visual, monitoramento, QA ou revisão de cliente. |
pdf | arquivo PDF | Sempre usa Chromium. Use para registros de página duráveis, trilhas de auditoria, relatórios ou revisão offline. |
Renderização de navegador e viewport
Essas opções importam apenas quando render=true, format=screenshot, ou format=pdf. Se a renderização estiver desligada e a saída for text/html/markdown/json, as opções de viewport são ignoradas.
| Parâmetro | Tipo / padrão | Descrição |
|---|---|---|
render_wait | ms, padrão 0 | Esperar extra após o carregamento inicial da página antes da captura/extração. Faixa: 0..15000. Não inclui o tempo de inicialização ou navegação do Chromium. |
viewport_width | número, padrão 1365 | Largura do viewport do navegador. O modo CSS aceita 320..3840; o modo Windows aceita pixels de display físico até 7680. |
viewport_height | número, padrão 768 | Altura do viewport do navegador. O modo CSS aceita 320..4000; o modo Windows aceita pixels de display físico até 8000. |
pixels | css ou windows | css significa que os valores do viewport são pixels CSS do navegador. windows significa que você passa pixels das Configurações de Exibição do Windows e o ScraperFly os converte usando display_scale. |
display_scale | número, padrão 150 | Usado apenas com pixels=windows. Aceita 125, 150, 200 ou 1.25, 1.5, 2. |
Opções de arquivo visual
Essas opções se aplicam apenas a format=screenshot e format=pdf. Respostas bem-sucedidas também são salvas como artefatos baixáveis no log de solicitações.
| Parâmetro | Tipo / padrão | Descrição |
|---|---|---|
file_type | jpg para captura de tela, pdf para PDF | A captura de tela suporta jpg, jpeg, png, webp. PDF suporta apenas pdf. BMP não é suportado. |
download | booleano | true retorna Content-Disposition: attachment. false retorna visualização inline quando o cliente a suporta. |
filename | string | Nome de arquivo opcional. A extensão é normalizada a partir de file_type. |
Exemplos do Postman
Cole isso diretamente no Postman como exemplos de URL ou referências de corpo de solicitação. Os parâmetros de consulta GET e o corpo JSON POST usam os mesmos nomes de opção.
Markdown de uma página simples
Use uma URL GET simples quando você quiser uma verificação rápida de sanidade do Postman para saída de Markdown limpa.
https://scraperfly.com/api/v1?url=https://example.com&format=markdown
PDF com viewport de tamanho Windows
Use controles de viewport quando um arquivo visual deve corresponder a um tamanho de display de desktop real.
https://scraperfly.com/api/v1?url=https://example.com&format=pdf&premium=true&render_wait=10000&viewport_width=2560&viewport_height=1600&pixels=windows&display_scale=150&file_type=pdf&download=true
Corpo JSON POST com as mesmas opções
Troque para POST quando a solicitação tiver muitas opções e um corpo JSON for mais fácil de revisar ou armazenar.
POST https://scraperfly.com/api/v1
apikey: YOUR_API_KEY_HERE
content-type: application/json
{
"url": "https://example.com",
"format": "screenshot",
"premium": true,
"render_wait": 10000,
"viewport_width": 1280,
"viewport_height": 720,
"pixels": "css",
"file_type": "jpg",
"download": true
}
Exemplo Avançado (Premium + Render + Cabeçalhos + País)
Use esta configuração quando um site bloquear o tráfego padrão. Isso habilita o roteamento de proxy premium, executa um navegador headless, mantém cabeçalhos selecionados e solicita um proxy específico do país. Se uma página ainda falhar, tente novamente com backoff exponencial, reduza a concorrência ou teste outro país.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36" \
-H "Cookie: SESSIONID=27382738"
const params = new URLSearchParams({
url: "https://example.com",
premium: "true",
render: "true",
keep_headers: "true",
country: "US"
});
const res = await fetch("https://scraperfly.com/api/v1?" + params.toString(), {
headers: {
apikey: "YOUR_API_KEY_HERE",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36",
"Cookie": "SESSIONID=27382738"
}
});
const html = await res.text();
console.log(html);
import requests
params = {
"url": "https://example.com",
"premium": "true",
"render": "true",
"keep_headers": "true",
"country": "US"
}
headers = {
"apikey": "YOUR_API_KEY_HERE",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36",
"Cookie": "SESSIONID=27382738"
}
res = requests.get("https://scraperfly.com/api/v1", params=params, headers=headers, timeout=30)
print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$params = http_build_query([
"url" => "https://example.com",
"premium" => "true",
"render" => "true",
"keep_headers" => "true",
"country" => "US",
]);
$ch = curl_init($endpoint . "?" . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"apikey: YOUR_API_KEY_HERE",
"User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36",
"Cookie: SESSIONID=27382738",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main
import (
"fmt"
"io"
"net/http"
"net/url"
"time"
)
func main() {
q := url.Values{}
q.Set("url", "https://example.com")
q.Set("premium", "true")
q.Set("render", "true")
q.Set("keep_headers", "true")
q.Set("country", "US")
endpoint := "https://scraperfly.com/api/v1?" + q.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36")
req.Header.Set("Cookie", "SESSIONID=27382738")
client := &http.Client{ Timeout: 30 * time.Second }
resp, err := client.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
http.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36");
http.DefaultRequestHeaders.Add("Cookie", "SESSIONID=27382738");
var endpoint = "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US";
var html = await http.GetStringAsync(endpoint);
Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NORMAL)
.build();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US"))
.header("apikey", "YOUR_API_KEY_HERE")
.header("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36")
.header("Cookie", "SESSIONID=27382738")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
req["User-Agent"] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36"
req["Cookie"] = "SESSIONID=27382738"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.read_timeout = 30
http.request(req)
end
puts res.body
Renderização JS (Exemplo Rápido)
Para páginas pesadas em JavaScript, defina render=true. Use isso quando o HTML fonte não contiver os dados e a página precisar de execução do navegador primeiro.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
Autenticação & Créditos Restantes
O ScraperFly usa chaves de API para autorização. Recomendado: envie sua chave pelo cabeçalho apikey. O ponto de extremidade /status retorna seus créditos restantes e informações da conta.
curl "https://scraperfly.com/api/v1/status" \
-H "apikey: YOUR_API_KEY_HERE"
const res = await fetch("https://scraperfly.com/api/v1/status", {
headers: { apikey: "YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);
import requests
res = requests.get("https://scraperfly.com/api/v1/status", headers={"apikey": "YOUR_API_KEY_HERE"})
print(res.json())
<?php
$ch = curl_init("https://scraperfly.com/api/v1/status");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$out = curl_exec($ch);
curl_close($ch);
echo $out;
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://scraperfly.com/api/v1/status", nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
var json = await http.GetStringAsync("https://scraperfly.com/api/v1/status");
Console.WriteLine(json);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1/status"))
.header("apikey", "YOUR_API_KEY_HERE")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1/status")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.request(req)
end
puts res.body
Tratamento de Erros
Erros são retornados como JSON com uma forma estável. Sempre inspecione o status HTTP + error.code para decidir se deve tentar novamente.
{
"error": {
"code": "validation_error",
"status": 422,
"context": [
{
"url": {
"type": "invalid_url",
"message": "missing url"
}
}
]
}
}
Tente novamente em rede/429/temporário 5xx. Não tente novamente em URL inválida ou chave de API inválida.
Códigos de Erro Comuns
| HTTP | Tipo | Significado |
|---|---|---|
| 400 | missing_url | Nenhum parâmetro url válido fornecido. |
| 400 | invalid_url | Valor inválido em url. |
| 401 | missing_api_key | Nenhuma chave de API fornecida. |
| 403 | invalid_api_key | A chave de API é inválida ou desativada. |
| 403 | forbidden | Créditos insuficientes ou sem acesso ao recurso. |
| 429 | rate_limited | Solicitações concorrentes demais. Diminua a velocidade ou faça upgrade. |
| 429 | usage_limit_reached | Limite do plano/mensal atingido. |
| 500 | internal_error | Erro do servidor. Tente novamente com backoff. |
Casos de Uso Comuns
Mantenha os padrões de produção comuns em um bloco com abas: comece simples, depois adicione roteamento, renderização, cabeçalhos ou backoff apenas quando o alvo provar que precisa deles.
1) Proxies Premium
Ative premium=true para alvos mais difíceis. Adicione country quando a resposta mudar por mercado ou localização.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE"
2) Cabeçalhos Personalizados (User-Agent / Cookies)
Use keep_headers=true quando o contexto do alvo for importante e você precisar passar cabeçalhos de solicitação selecionados.
curl "https://scraperfly.com/api/v1?url=https://example.com&keep_headers=true" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0" \
-H "Accept-Language: en-US,en;q=0.9" \
-H "Cookie: SESSIONID=27382738"
3) Renderização JS
Para SPA, Next.js e páginas construídas em navegador, defina render=true para que o ScraperFly aguarde a saída do JavaScript antes de extrair a resposta.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
4) Anti-bot & Páginas de Desafio
Se você receber conteúdo de desafio ou bloqueado, combine roteamento premium, renderização de navegador, cabeçalhos permitidos realistas, menor concorrência e backoff de tentativa.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0" \
-H "Accept-Language: en-US,en;q=0.9"