ScraperFlyAPI de dados web pronta para IA

docs

Documentação para sua primeira solicitação ScraperFly

A API é intencionalmente direta: envie uma URL, escolha os controles que você precisa e manipule o HTML retornado ou a resposta extraída em sua aplicação.

Documentação

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.

Ponto de extremidade

/api/v1

Use parâmetros de consulta GET ou JSON POST. Ambas as formas de solicitação retornam o mesmo resultado.

Autenticação

apikey cabeçalho

Mantenha as chaves no lado do servidor e gire-as a partir do painel sempre que necessário.

Créditos

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.

PremiumRenderizarCusto em créditos
falsefalse1
falsetrue5
truefalse10
truetrue25
Dicas para controlar custos
  • Comece com premium=false, render=false para alvos fáceis.
  • Ative render=true apenas para páginas pesadas em JS (React/Vue/Next.js).
  • Use country quando 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.).

8 exemplos
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âmetroTipoDescrição
urlobrigatórioURL do site alvo que você deseja raspar, por exemplo url=https://example.com.
premiumopcional, booleanoUsa pools de proxy de maior qualidade para alvos mais difíceis. Custa mais créditos.
countryopcionalPaís do proxy solicitado, por exemplo US. Os logs de uso armazenam o país e a cidade reais do proxy.
renderopcional, booleanoRenderização de navegador headless para páginas que requerem JavaScript. Ativado automaticamente para screenshot e pdf.
keep_headersopcional, booleanoTransfira seus próprios cabeçalhos (cookies, user-agent, accept-language, etc.).
formatopcionalFormato de saída: html, text, markdown, json, screenshot, ou pdf.

Formatos de saída

formatoRespostaQuando usar
htmlHTMLPadrão. Use quando você quiser a fonte bruta ou HTML renderizado para seu próprio parser.
texttexto simplesUse quando você precisar de texto limpo e legível sem ruído de navegação/layout.
markdownMarkdownUse para prompts LLM, RAG, docs, resumos e indexação.
jsonJSONUse para metadados, título, cabeçalhos, links, texto limpo e Markdown em uma única resposta.
screenshotarquivo de imagemSempre usa Chromium. Use para prova visual, monitoramento, QA ou revisão de cliente.
pdfarquivo PDFSempre 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âmetroTipo / padrãoDescrição
render_waitms, padrão 0Esperar 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_widthnúmero, padrão 1365Largura do viewport do navegador. O modo CSS aceita 320..3840; o modo Windows aceita pixels de display físico até 7680.
viewport_heightnúmero, padrão 768Altura do viewport do navegador. O modo CSS aceita 320..4000; o modo Windows aceita pixels de display físico até 8000.
pixelscss ou windowscss 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_scalenúmero, padrão 150Usado 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âmetroTipo / padrãoDescrição
file_typejpg para captura de tela, pdf para PDFA captura de tela suporta jpg, jpeg, png, webp. PDF suporta apenas pdf. BMP não é suportado.
downloadbooleanotrue retorna Content-Disposition: attachment. false retorna visualização inline quando o cliente a suporta.
filenamestringNome 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.

Pronto para Postman

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.

8 exemplos
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.

8 exemplos
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"
        }
      }
    ]
  }
}
Regras de Tentativa

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

HTTPTipoSignificado
400missing_urlNenhum parâmetro url válido fornecido.
400invalid_urlValor inválido em url.
401missing_api_keyNenhuma chave de API fornecida.
403invalid_api_keyA chave de API é inválida ou desativada.
403forbiddenCréditos insuficientes ou sem acesso ao recurso.
429rate_limitedSolicitações concorrentes demais. Diminua a velocidade ou faça upgrade.
429usage_limit_reachedLimite do plano/mensal atingido.
500internal_errorErro 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.

4 padrões

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"