Pular para o conteúdo principal
POST
Pesquisa da Amazon
Informe o mercado. Ações: search, product, keywords, keyword_volume, reviews, price_history, offers, merchant_search e merchant_page. Consulte preços antes; max_charge_usd recusa pedidos acima do orçamento antes de criar o Run. Valores desconhecidos são null. Registre páginas e filtros observados sem afirmar prevalência populacional. Preserve série, moeda e data dos preços. Ofertas em cache não são preços de compra verificados. Leia result_url autenticado para resultados pendentes; dados nativos permanecem no Run.

Cabeçalhos

idempotency-key
string
obrigatório

Gere um novo valor exclusivo (de preferência um UUID aleatório) para cada consulta independente, mesmo com os mesmos parâmetros no mesmo dia. Recupere a mesma execução com a chave e os parâmetros originais para obter o Run original sem outra cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não inicia um novo Run. As chaves opacas existentes continuam válidas para recuperação.

Minimum string length: 1

Corpo

application/json

merchant_search: query e idioma opcional; merchant_page: url pública. search: query e page opcional; product/reviews/offers: asin exato. reviews aceita review_pages, review_rating, review_sort, verified_only e review_keyword. keywords: query e language/limit/offset opcionais, apenas us/en. keyword_volume: keywords e idioma. max_charge_usd limita a cobrança antes do Run. price_history: asin e days opcional, padrão 180. Campos incompatíveis são recusados antes da cobrança. Sem alterações de produtos, estimativas de taxas ou monitoramento automático.

action
enum<string>
obrigatório
Opções disponíveis:
search,
product,
keywords,
keyword_volume,
reviews,
price_history,
offers,
merchant_search,
merchant_page
country
string
obrigatório

Mercado da Amazon explícito. Consultas gerais aceitam us, gb, de, fr, it, es, ca, jp, in e au; termos relacionados apenas us/en. keyword_volume aceita seus próprios pares de região e idioma.

Minimum string length: 1
provider
enum<string> | null

Padrão auto: seleciona o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado precisa ser compatível com a solicitação e permitido pela sua Key; ele não usa fallback para outro provedor de dados. Os valores disponíveis estão listados abaixo.

Opções disponíveis:
auto,
serpapi,
dataforseo,
apify,
keepa,
serper
max_charge_usd
string | null

String decimal exata em USD (mínimo de 2 e máximo de 6 casas decimais, com uma única grafia canônica). Some usando aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante.

Maximum string length: 20
Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
review_pages
integer | null
Intervalo obrigatório: 1 <= x <= 10
review_rating
integer | null
Intervalo obrigatório: 1 <= x <= 5
review_sort
enum<string> | null
Opções disponíveis:
recent,
helpful
verified_only
boolean | null
review_keyword
string | null
Required string length: 1 - 200
url
string | null
Required string length: 1 - 2048
Pattern: ^https?:\/\/
query
string | null
Required string length: 1 - 200
keywords
string[] | null
Required array length: 1 - 1000 elements
Minimum string length: 1
asin
string | null
Pattern: ^[A-Z0-9]{10}$
page
integer | null
Intervalo obrigatório: 1 <= x <= 20
limit
integer | null
Intervalo obrigatório: 1 <= x <= 100
offset
integer | null
Intervalo obrigatório: 0 <= x <= 10000
language
string | null
Minimum string length: 1
days
integer | null
Intervalo obrigatório: x >= 1
task_id
string | null

Agrupe Runs relacionados, incluindo o fallback automático, em uma única Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los.

metadata

Campos de rastreamento opcionais, retornados no Run e disponíveis como filtros. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o preço ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1–500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.

Entradas inválidas são descartadas integralmente, não truncadas. A solicitação continua, e o Run retorna os campos que foram armazenados.

Resposta

Success

id
string
obrigatório
run_url
string
obrigatório

Abra este Run no console. Requer associação ao Workspace.

provider
string
obrigatório
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
obrigatório
Pattern: ^\/.+$
endpoint_version
integer
obrigatório
status
enum<string>
obrigatório

QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte failure. STOPPED: interrompido antes do despacho. Leia charge_usd separadamente de status.

Opções disponíveis:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
obrigatório

Motivo da falha do Run. Não nulo somente quando status é FAILED.

input
object
obrigatório
output
object
obrigatório
provider_response
object | null
obrigatório

Não nulo somente quando status é COMPLETED.

  • Para respostas 2xx, output contém JSON nativo do provedor de dados (qualquer estrutura) ou nulo para um corpo vazio.
  • Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é nulo.

Os campos confidenciais são removidos de ambos os corpos.

charge_usd
string | null
obrigatório

Cobrança histórica total dos Runs listados, incluindo os reproduzidos ou lidos. É null até que todos sejam liquidados. Não é uma nova despesa da solicitação atual; request_charge a informa separadamente. Falhas também podem ser cobradas.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
obrigatório

Base de cobrança de um único Run ou nulo para um total de vários Runs. Leia runs[].charge_basis para cada cobrança.

stoppable
boolean
obrigatório

Indica se uma solicitação de interrupção pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do despacho.

stop_requested_at
string<date-time> | null
obrigatório

Momento em que uma interrupção foi solicitada. O Run ainda pode continuar se o despacho já tiver começado.

created_at
string<date-time>
obrigatório

carimbo de data e hora UTC ISO-8601

started_at
string<date-time> | null
obrigatório

carimbo de data e hora UTC ISO-8601

completed_at
string<date-time> | null
obrigatório

carimbo de data e hora UTC ISO-8601

task_id
string | null
obrigatório
metadata
object
obrigatório

Seus campos de acompanhamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1–500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.
action
enum<string>
obrigatório
Opções disponíveis:
search,
product,
keywords,
keyword_volume,
reviews,
price_history,
offers,
merchant_search,
merchant_page
result_status
enum<string>
obrigatório
Opções disponíveis:
success,
no_result,
error,
pending
error
object | null
obrigatório
runs
object[]
obrigatório
result_url
string
obrigatório

Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run nativo e individual.

response_file
object

Corpo completo e de grande tamanho do provedor de dados, entregue como arquivo JSON. O Glasser aplica um limite de recursos de 32 MiB ao corpo capturado e ao arquivo serializado. body_field identifica o campo substituído; output é null ou provider_response.error é omitido. Os links de download expiram em no máximo uma hora. Get Run com autenticação renova a URL enquanto o arquivo estiver disponível, por 7 dias. Leituras e downloads não executam nem cobram outro Run. Se state for link_pending, leia o mesmo Run para preparar o link sem outra execução ou cobrança. A URL concede acesso temporário de leitura: compartilhe-a apenas com os destinatários pretendidos.

review_invitation
object

Aparece no máximo uma vez por Run, na primeira entrega de alguns Runs concluídos. Depois de usar este resultado na tarefa, envie uma avaliação conforme indicado em instruction e continue. É opcional; nunca afeta o Run nem a cobrança.

request_charge
object

Evidência de admissão e cobrança da solicitação atual. Preserve created_run_ids durante o trabalho do usuário e conte cada Run liquidado uma única vez. Alterar task_id não transforma uma reprodução idempotente em um novo Run. A leitura de resultado tem cobrança zero e listas de admissão vazias.