> ## Documentation Index > Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pesquisa na web > Pesquise na web, em notícias, lugares e outros conteúdos públicos, recupere uma página ou obtenha uma resposta com fontes. Escolha uma ação e forneça uma consulta ou URL conforme descrito abaixo. Cada ação retorna `output` normalizado; verifique `result_status` para a entrega. Notícias, lugares, scholar, compras, imagens, vídeos e similares expõem `output.items[]` com campos fixos por linha; answer expõe `output.answer` e `citations[]`. Scrape expõe `text`, `markdown`, `html` e `raw_html`; formatos ausentes são null. A saída nativa do Provider não é repetida em `output`; ela permanece no Run e pode ser lida com [Get Run](https://glasser.ai/docs/pt/api-reference/runs/get.md). O Glasser não converte HTML em texto nem avalia a qualidade semântica com base na redação ou no tamanho. Search retorna `output.results[]` e é compatível com `time_range: day | week | month | year`. Uma resposta vazia, mas válida, é `no_result` e mantém o formato da ação: `results` ou `items` é `[]`, e uma resposta vazia é `answer: null` com `citations: []`. Scrape não tem resposta vazia: uma página que não pode ser entregue é `error`, com `output: null` e o motivo em `error.code`. Fetch (`scrape`) usa Serper e depois Firecrawl dentro de um orçamento padrão de 30 segundos por solicitação. HTML ou solicitações explícitas de idade do cache vão diretamente para o Firecrawl. O enriquecimento de X/Twitter e LinkedIn exclui o Firecrawl. Um Provider nomeado nunca usa fallback. Saída vazia ou inválida, erros do Provider, timeout ou formatos compatíveis ausentes podem acionar o fallback. O conteúdo entregue vem do Run final; conteúdo de capturas diferentes não é mesclado. `charge_usd` totaliza `runs` desta resposta, incluindo falhas cobradas e resultados vazios, e é null até que todos os Runs sejam concluídos. O ciclo de vida do Run final permanece em `status`; somente `COMPLETED` não comprova a entrega de conteúdo. Para trabalhos pendentes, siga o [result\_url](https://glasser.ai/docs/pt/api-reference/solutions/gtm/web_research/result.md) autenticado para manter a saída normalizada e o total de cobranças. [Get Run](https://glasser.ai/docs/pt/api-reference/runs/get.md) continua nativo e informa uma cobrança individual. O polling não cria Runs e não retoma o fallback. Uma nova tentativa intencional de POST usa a mesma Idempotency-Key e os mesmos parâmetros de execução, reutiliza Runs existentes e inicia uma nova janela de solicitação. Consulte [Provider selection and charges](https://glasser.ai/docs/pt/api-reference/solutions/overview.md#how-provider-selection-works). ## Saída por ação Cada campo está presente em todas as linhas; um valor que o Provider não informa é `null`. Os campos seguem as [convenções de campos](https://glasser.ai/docs/pt/api-reference/solutions/overview.md#field-conventions). | `action` | `output` | | - | - | | `search` | `results[]`: `url`, `title`, `snippet`, `position`, `published_at`, `date_text`, `date` (obsoleto) | | `news` | `items[]`: `title`, `url`, `source`, `published_at`, `date_text`, `snippet` | | `places` | `items[]`: `name`, `address`, `category`, `rating`, `reviews`, `phone`, `website`, `latitude`, `longitude`, `google_cid` | | `scholar` | `items[]`: `title`, `url`, `snippet`, `publication`, `year`, `cited_by`, `pdf_url` | | `shopping` | `items[]`: `title`, `url` (Google Shopping `page`), `merchant_url`, `google_product_id`, `price_text`, `seller`, `rating`, `reviews`, `image_url` | | `images` | `items[]`: `title`, `image_url`, `thumbnail_url`, `source_url`, `source`, `width`, `height` | | `videos` | `items[]`: `title`, `url`, `channel`, `source`, `date_text`, `duration_text`, `snippet`, `thumbnail_url` | | `answer` | `answer`, `citations[]`: `url`, `title`, `published_at` | | `scrape` | `url`, `final_url`, `title`, `text`, `markdown`, `html`, `raw_html`, `text_character_limit`, `cached`, `fetched_at`, `quality` (obsoleto) | | `similar` | `items[]`: `url`, `title`, `exa_similarity_score`, `published_at`, `author` | * `published_at` é um timestamp UTC ISO 8601, preenchido somente quando o Provider informa um timestamp de máquina (Exa `publishedDate`, notícias do SerpApi `iso_date`). `fetched_at` tem o mesmo formato. * `date_text` é o texto de exibição do Google exatamente como retornado. Ele pode ser relativo ao `completed_at` do Run ("3 horas atrás") e nunca é analisado. * search `date` está obsoleto: contém o texto de exibição do Google para Serper e SerpApi e o `publishedDate` bruto do Exa para Exa. Use `published_at` ou `date_text`. * `snippet` é o trecho curto do Google ou o destaque extraído do Exa para Exa; nunca é o texto completo da página. * `price_text` e `duration_text` são strings de exibição, não analisadas; a moeda do preço segue `country`. * `rating` é a média de estrelas de 1 a 5 do Google e `reviews` é uma contagem. `source` é o nome do publisher ou do site. * `address` é o texto do próprio Provider; o Serper pode retornar somente a linha do endereço. * `exa_similarity_score` é a pontuação própria do Exa, comparável somente dentro de uma única resposta. Similar exclui páginas do host da URL solicitada. * `text_character_limit` é o limite de caracteres que o Glasser pediu ao Provider para aplicar (10000 para Exa); textos exatamente desse tamanho podem ser truncados. `cached` informa se o Provider forneceu a página a partir do cache. * `quality` é sempre `unverified` e será removido na próxima revisão com breaking change. ```json { "action": "news", "provider": "serper", "status": "COMPLETED", "result_status": "success", "output": { "items": [ { "title": "Ripple, Stripe-owned Privy partner to bring embedded wallets to XRP Ledger", "url": "https://www.theblock.co/news/business/2026-10-13-stripe-privy-ripple-xrp-ledger-wallets-418463", "source": "The Block", "published_at": null, "date_text": "18 hours ago", "snippet": "The integration will allow developers to add XRP Ledger wallets to their apps using Privy's infrastructure." } ] }, "charge_usd": "0.0011", "runs": [{ "provider": "serper", "status": "COMPLETED", "charge_usd": "0.0011" }], "result_url": "/v1/solutions/gtm/web_research/result?token=…" } ``` ## OpenAPI ````yaml /openapi.pt.json post /v1/solutions/gtm/web_research openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: >- Uma chave, sem contrato, pagamento por chamada, para todas as APIs pagas adquiridas no atacado. Cada resposta contém x-request-id; cada corpo de erro contém o mesmo envelope. servers: - url: https://api.glasser.ai security: [] tags: - name: Solutions - name: Endpoints - name: Runs - name: Balance paths: /v1/solutions/gtm/web_research: post: tags: - Solutions summary: Pesquisa na web description: >- Pesquise e recupere conteúdo público da web. Cada ação retorna uma saída normalizada com o id, o provedor de dados e o status do ciclo de vida do último Run: search fornece output.results[], news / places / scholar / shopping / images / videos / similar fornecem output.items[] com campos fixos por linha, answer fornece output.answer e citations[], e scrape fornece campos de conteúdo fixos. Para scrape, leia output.text, output.markdown, output.html e output.raw_html. Formatos ausentes são null; nenhuma conversão de HTML para texto é realizada. A saída nativa do provedor de dados não é repetida em output; leia-a no Run com GET /v1/runs/:id. Para search, leia output.results[]. Leia result_status separadamente de status: success, partial, no_result, error ou pending. COMPLETED significa que o Run final foi concluído com uma resposta do provedor de dados; isso não comprova que o conteúdo seja utilizável. output é null em caso de falha na entrega ou enquanto estiver pendente. partial lista missing_formats. A semântica do conteúdo permanece não verificada; o texto e o tamanho não determinam a qualidade. charge_usd é o total dos runs desta resposta, incluindo falhas pagas e resultados vazios. Ele é null até que todos os Runs listados sejam concluídos. runs[] contém cobranças individuais, status e charge_basis, sem corpos duplicados. Um total de vários Runs tem charge_basis=null. A resposta é um resultado de Solution, não o Run armazenado. GET /v1/runs/:id continua sendo nativo e tem uma cobrança individual. Para QUEUED/RUNNING (HTTP 202), consulte por polling o result_url autenticado na origem da API. Essa leitura retorna o mesmo contrato normalizado e o total, não cria Runs e não retoma o fallback. Resultados terminais retornam HTTP 200, inclusive erros de negócio; inspecione result_status e error. Reutilize o mesmo Idempotency-Key e os parâmetros de execução para uma nova tentativa intencional. Scrape usa automaticamente Serper e depois Firecrawl dentro de um orçamento padrão de 90000 ms por solicitação. Cada chamada ao provedor de dados começa com a janela de seu Endpoint; quando essa janela excederia o orçamento da solicitação, Serper, Firecrawl e Exa usam o tempo restante real, reservando tempo para liquidação e resposta. HTML ou uma idade de cache explícita vão diretamente para Firecrawl. O enriquecimento de X/Twitter e LinkedIn exclui Firecrawl; Exa e DataForSEO são somente explícitos. Um provedor de dados nomeado nunca usa fallback. Saídas vazias ou inválidas, erros do provedor de dados, timeout e formatos compatíveis ausentes podem acionar o fallback quando outra rota puder melhorar a entrega. Não há mesclagem de conteúdo entre provedores de dados. Se nenhum Run for admitido, retorne o erro de admissão. Quando formats é omitido, Serper/Exa verificam text e Firecrawl/DataForSEO verificam markdown; todos os formatos nativos disponíveis são mapeados para output. max_charge_usd cobre todos os Runs desta solicitação, incluindo replays. Os orçamentos ficam apenas na memória da solicitação; uma nova tentativa inicia uma nova janela de tempo, mas não pode alterar o prazo de um Run existente. Search time_range aceita day, week, month e year. Auto seleciona um provedor de dados compatível com o filtro. Resultados de busca vazios não acionam fallback pago. operationId: gtm-web-research parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- Gere um valor exclusivo para cada execução pretendida (recomenda-se um UUID). Tente novamente com a mesma chave e os mesmos parâmetros de execução para recuperar o Run original sem uma segunda cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não atualiza o Run original. required: true requestBody: content: application/json: schema: type: object properties: action: anyOf: - type: string enum: - search - news - places - scholar - shopping - images - videos - answer - scrape - similar description: >- Padrão: search. - Forneça query para search, news, places, scholar, shopping, images, videos ou answer. - Forneça url para scrape ou similar. - type: 'null' provider: anyOf: - type: string enum: - auto - serper - serpapi - exa - dataforseo - firecrawl description: >- Padrão auto: seleciona o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado deve 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. - type: 'null' query: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' formats: type: array items: type: string enum: - text - markdown - html - raw_html minItems: 1 maxItems: 4 description: >- Somente para scrape. Quando omitido, usa o padrão nativo do provedor de dados selecionado: text para Serper/Exa, markdown para Firecrawl/DataForSEO. Os formatos solicitados orientam o roteamento e o fallback; output expõe os campos fixos text/markdown/html/raw_html. html significa HTML limpo; raw_html significa HTML original. Auto usa Serper e depois Firecrawl. Solicitações de HTML vão diretamente para Firecrawl. Leia result_status e missing_formats para verificar a entrega; um campo null não solicitado não é um resultado parcial. Firecrawl não fornece text; a Glasser não converte HTML em texto. X/Twitter e as rotas de enriquecimento são excluídos do Firecrawl. timeout_ms: type: integer minimum: 1000 maximum: 120000 description: >- Somente para scrape. Padrão 90000. Orçamento de execução para esta solicitação da API, incluindo o fallback sequencial. Cada chamada ao provedor de dados começa com a janela de seu Endpoint, em vez de uma parte do tempo restante; a chamada mantém a janela completa quando ela, junto com o tempo de liquidação, cabe no orçamento restante. Quando a janela completa excederia o orçamento da solicitação, Serper, Firecrawl e Exa usam o tempo restante real até o limite da janela de seu Endpoint, reservando tempo para liquidação e resposta; uma etapa só é ignorada quando resta menos de 1 segundo de tempo de chamada. Uma nova tentativa inicia uma nova janela de solicitação e reutiliza Runs existentes por meio da idempotência do Run. max_charge_usd: type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- String decimal exata em USD (mínimo de 2, máximo de 6 casas decimais, uma única grafia canônica). Faça a soma com aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante. allOf: - pattern: ^\d{1,12}\. description: >- Somente para scrape. Cobrança total máxima dos Runs nesta solicitação, incluindo Runs reproduzidos. Antes de um novo Run, as Cobranças concluídas mais a Cobrança máxima dele devem caber no limite. Um Run não concluído interrompe o fallback. Omita para não impor um limite do chamador; 0.00 não permite novos Runs pagos. cache_max_age_seconds: type: integer minimum: 0 maximum: 2592000 description: >- Somente para scrape. Idade máxima do cache do provedor de dados; 0 exige uma busca ao vivo. Rotas sem esse controle são excluídas. Auto seleciona Firecrawl (milissegundos); Exa explícito recebe horas inteiras arredondadas para baixo. Metadados desconhecidos de cache/busca permanecem null. time_range: type: string enum: - day - week - month - year description: >- Somente para search: restrinja os resultados ao último dia, semana, mês ou ano usando o filtro de tempo do Google. Omita para qualquer período. Auto usa apenas provedores de dados compatíveis com esse filtro (Serper e SerpApi). Exa é recusado quando este campo é fornecido. Este é um filtro do mecanismo de busca, não uma data de publicação verificada. country: anyOf: - type: string minLength: 2 maxLength: 60 description: >- País para ações do tipo search, como código ISO de duas letras ou nome do país. Padrão us. Não se aplica a scrape ou similar. É recusado com 400 quando o provedor nomeado não pode aplicá-lo. - type: 'null' language: anyOf: - type: string pattern: ^[A-Za-z]{2}$ description: >- Idioma para ações do tipo search, com duas letras, como en, de. Não se aplica a scrape ou similar. - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: >- Linhas a retornar. Mantenha o número pequeno: a regra de cobrança do endpoint roteado pode considerá-lo. Cada capacidade impõe um limite adicional. - type: 'null' task_id: anyOf: - type: string description: >- Agrupe Runs relacionados, incluindo o fallback automático, sob uma única Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los. - type: 'null' metadata: anyOf: - anyOf: - type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ - {} description: >- Campos opcionais de acompanhamento, 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 por inteiro, sem truncamento. A solicitação continua, e o Run retorna os campos armazenados. - type: 'null' additionalProperties: false required: true responses: '200': description: Sucesso content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebResearchResult' '202': description: Sucesso content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebResearchResult' '400': description: ValidationFailed | IdempotencyKeyRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationFailedEncoded' - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded' - $ref: '#/components/schemas/ValidationFailedEncoded' '401': description: Não autorizado content: application/json: schema: $ref: '#/components/schemas/UnauthorizedEncoded' '402': description: InsufficientBalance content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: EndpointNotPermitted | Proibido content: application/json: schema: anyOf: - $ref: '#/components/schemas/EndpointNotPermittedEncoded' - $ref: '#/components/schemas/ForbiddenEncoded' '409': description: IdempotencyConflict content: application/json: schema: $ref: '#/components/schemas/IdempotencyConflictEncoded' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimitedEncoded' '503': description: ServiceUnavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableEncoded' security: - bearer: [] components: schemas: WebResearchResult: type: object properties: id: type: string run_url: type: string description: Abra este Run no console. Requer associação ao Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- 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 envio. Leia charge_usd separadamente de status. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: Motivo da falha do Run. Não é null somente quando status é FAILED. input: type: object output: anyOf: - anyOf: - type: object properties: url: type: string description: >- A URL solicitada ou a URL final quando o provedor de dados informar uma. final_url: anyOf: - type: string - type: 'null' description: >- A URL após o redirecionamento conforme informada pelo provedor de dados (Firecrawl, Exa). Null quando o provedor de dados não informar uma. title: anyOf: - type: string - type: 'null' text: anyOf: - type: string - type: 'null' markdown: anyOf: - type: string - type: 'null' html: anyOf: - type: string - type: 'null' raw_html: anyOf: - type: string - type: 'null' text_character_limit: anyOf: - type: integer - type: 'null' description: >- O limite de caracteres que o Glasser pediu ao provedor de dados para aplicar ao texto (10000 para Exa); portanto, um texto com exatamente esse tamanho pode ser truncado. Null quando nenhum limite foi aplicado. cached: anyOf: - type: boolean - type: 'null' description: >- Indica se o provedor de dados forneceu a página a partir do cache (cacheState do Firecrawl, status source do Exa). Null quando o provedor de dados não informar. fetched_at: anyOf: - type: string - type: 'null' description: >- Quando o provedor de dados buscou a página, em UTC ISO 8601 (fetch_time do DataForSEO). Null quando o provedor de dados não informar. quality: type: string enum: - unverified description: >- Obsoleto: sempre 'unverified'; nenhuma verificação de conteúdo é aplicada. Mantido para compatibilidade e será removido na próxima revisão com alterações incompatíveis. required: - url - final_url - title - text - markdown - html - raw_html - text_character_limit - cached - fetched_at - quality additionalProperties: false - type: object properties: results: type: array items: type: object properties: url: type: string title: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' description: >- O trecho curto do Google (Serper / SerpApi) ou o destaque extraído pelo Exa para Exa. Não é o texto completo da página. position: type: integer date: anyOf: - type: string - type: 'null' description: >- Obsoleto: use published_at ou date_text. Contém o texto de exibição do Google para Serper / SerpApi e o publishedDate bruto do Exa para Exa. published_at: anyOf: - type: string - type: 'null' description: >- Timestamp UTC ISO 8601, preenchido somente quando o provedor de dados informar um timestamp de máquina (publishedDate do Exa, iso_date de notícias do SerpApi); caso contrário, null. date_text: anyOf: - type: string - type: 'null' description: >- Texto de exibição do Google exatamente como retornado pelo provedor de dados (data do Serper / SerpApi). Pode ser relativo ao completed_at do Run, como '3 hours ago', e nunca é analisado. required: - url - title - snippet - position - date - published_at - date_text additionalProperties: false required: - results additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: >- Nome do editor ou site conforme exibido pelo provedor de dados. published_at: anyOf: - type: string - type: 'null' description: >- Timestamp UTC ISO 8601, preenchido somente quando o provedor de dados informar um timestamp de máquina (publishedDate do Exa, iso_date de notícias do SerpApi); caso contrário, null. date_text: anyOf: - type: string - type: 'null' description: >- Texto de exibição do Google exatamente como retornado pelo provedor de dados (data do Serper / SerpApi). Pode ser relativo ao completed_at do Run, como '3 hours ago', e nunca é analisado. snippet: anyOf: - type: string - type: 'null' required: - title - url - source - published_at - date_text - snippet additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' address: anyOf: - type: string - type: 'null' description: >- Texto do endereço do provedor de dados, sem análise ou complementação. O Serper pode retornar somente a linha da rua. category: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: Avaliação média em estrelas do Google, de 1 a 5. reviews: anyOf: - type: integer - type: 'null' description: >- Número de avaliações do Google que compõem a classificação. phone: anyOf: - type: string - type: 'null' website: anyOf: - type: string - type: 'null' latitude: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' longitude: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' google_cid: anyOf: - type: string - type: 'null' description: >- CID do Google Maps do local (cid do Serper, data_cid do SerpApi). required: - name - address - category - rating - reviews - phone - website - latitude - longitude - google_cid additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' publication: anyOf: - type: string - type: 'null' year: anyOf: - type: integer - type: 'null' cited_by: anyOf: - type: integer - type: 'null' pdf_url: anyOf: - type: string - type: 'null' required: - title - url - snippet - publication - year - cited_by - pdf_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' description: A página do produto no Google Shopping. merchant_url: anyOf: - type: string - type: 'null' description: >- URL da oferta do comerciante quando informada pelo provedor de dados (link do SerpApi); null para o Serper. google_product_id: anyOf: - type: string - type: 'null' description: >- ID do produto no catálogo do Google Shopping (productId do Serper, product_id do SerpApi). price_text: anyOf: - type: string - type: 'null' description: >- Preço de exibição do provedor de dados, como '$69.00'. Não é analisado; a moeda segue o país. seller: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: Avaliação média em estrelas do Google, de 1 a 5. reviews: anyOf: - type: integer - type: 'null' description: >- Número de avaliações do Google que compõem a classificação. image_url: anyOf: - type: string - type: 'null' required: - title - url - merchant_url - google_product_id - price_text - seller - rating - reviews - image_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' image_url: anyOf: - type: string - type: 'null' thumbnail_url: anyOf: - type: string - type: 'null' source_url: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: >- Nome do editor ou site conforme exibido pelo provedor de dados. width: anyOf: - type: integer - type: 'null' height: anyOf: - type: integer - type: 'null' required: - title - image_url - thumbnail_url - source_url - source - width - height additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' channel: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: >- Plataforma de vídeo conforme exibida pelo provedor de dados, como YouTube. date_text: anyOf: - type: string - type: 'null' description: >- Texto de exibição do Google exatamente como retornado pelo provedor de dados (data do Serper / SerpApi). Pode ser relativo ao completed_at do Run, como '3 hours ago', e nunca é analisado. duration_text: anyOf: - type: string - type: 'null' description: Duração exibida conforme retornada, como '4:39'. snippet: anyOf: - type: string - type: 'null' thumbnail_url: anyOf: - type: string - type: 'null' required: - title - url - channel - source - date_text - duration_text - snippet - thumbnail_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' exa_similarity_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Pontuação de similaridade própria do Exa para esta página. Compare-a somente dentro de uma resposta; ela não é comparável às pontuações de outros provedores de dados. published_at: anyOf: - type: string - type: 'null' description: >- Timestamp UTC ISO 8601, preenchido somente quando o provedor de dados informa um timestamp de máquina (Exa publishedDate, SerpApi news iso_date); caso contrário, null. author: anyOf: - type: string - type: 'null' required: - url - title - exa_similarity_score - published_at - author additionalProperties: false required: - items additionalProperties: false - type: object properties: answer: anyOf: - type: string - type: 'null' citations: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' published_at: anyOf: - type: string - type: 'null' description: >- Timestamp UTC ISO 8601, preenchido somente quando o provedor de dados informa um timestamp de máquina (Exa publishedDate, SerpApi news iso_date); caso contrário, null. required: - url - title - published_at additionalProperties: false required: - answer - citations additionalProperties: false - type: 'null' description: >- Campos normalizados por ação. A saída nativa do provedor de dados não é repetida aqui; ela permanece no Run (GET /v1/runs/:id). Os valores que o provedor de dados não informa são null. - search: results[]: url, title, snippet (trecho do Google; destaque extraído pelo Exa para o Exa), position, published_at, date_text, date (obsoleto) - news: items[]: title, url, source, published_at, date_text, snippet - places: items[]: name, address (texto do provedor de dados; pode conter somente a linha da rua), category, rating (1–5), reviews, phone, website, latitude, longitude, google_cid - scholar: items[]: title, url, snippet, publication, year, cited_by, pdf_url - shopping: items[]: title, url (página do Google Shopping), merchant_url, google_product_id, price_text, seller, rating (1–5), reviews, image_url - images: items[]: title, image_url, thumbnail_url, source_url, source, width, height - videos: items[]: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url - answer: answer, citations[]: url, title, published_at - scrape: url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality (obsoleto) - similar: items[]: url, title, exa_similarity_score, published_at, author published_at é um timestamp UTC ISO 8601 e só é definido a partir de um timestamp de máquina do provedor de dados. date_text é o texto de exibição do Google conforme retornado; ele pode ser relativo a completed_at do Run e nunca é interpretado. rating é a média de estrelas de 1–5 do Google; reviews é uma contagem. source é o nome de um editor ou site. exa_similarity_score é a pontuação própria do Exa e só pode ser comparada dentro de uma única resposta. provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Status HTTP retornado pelo provedor de dados. Verifique-o mesmo quando o Run estiver COMPLETED. error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: >- Não nulo somente quando status é COMPLETED. - Para respostas 2xx, output contém JSON nativo do provedor de dados (qualquer formato) ou null para um corpo vazio. - Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é null. Os campos sensíveis são removidos de ambos os corpos. charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- String decimal exata em USD (mínimo de 2 e máximo de 6 casas decimais, uma única grafia canônica). Some usando aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante. - type: 'null' description: >- Cobrança total dos Runs nesta resposta de Solution. Null até que todos os Runs listados sejam liquidados. Cada Run mantém sua própria cobrança; falhas também podem ser cobradas. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Base de cobrança de um único Run ou null para um total de vários Runs. Leia runs[].charge_basis para cada cobrança. stoppable: type: boolean description: >- Indica se uma solicitação de parada pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do dispatch. stop_requested_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' description: >- Momento em que uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado. created_at: type: string description: Timestamp UTC ISO-8601 format: date-time started_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- 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: type: string enum: - search - news - places - scholar - shopping - images - videos - answer - scrape - similar result_status: type: string enum: - success - partial - no_result - error - pending description: >- Status de entrega comercial, independente do ciclo de vida final do Run em status. success não é um veredito semântico sobre a qualidade do conteúdo. missing_formats: type: array items: type: string enum: - text - markdown - html - raw_html error: anyOf: - type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false - type: 'null' runs: type: array items: type: object properties: id: type: string run_url: type: string description: Abra este Run no console. Requer associação ao Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- 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 dispatch. Leia charge_usd separadamente de status. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: >- Motivo da falha do Run. Não nulo somente quando status é FAILED. input: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false output: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Status HTTP retornado pelo provedor de dados. Verifique-o mesmo quando o Run estiver COMPLETED. required: - http_status additionalProperties: false - type: 'null' charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- String decimal exata em USD (mínimo de 2 e máximo de 6 casas decimais, uma única grafia canônica). Some usando aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante. - type: 'null' description: >- Cobrança final como uma string decimal exata em USD. Null enquanto estiver QUEUED ou RUNNING. Um Run FAILED pode ter uma cobrança diferente de zero de acordo com o Price do Endpoint. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Cláusula de preço usada para calcular a cobrança. Null antes da liquidação ou quando nenhuma tentativa com o provedor de dados foi realizada. stoppable: type: boolean description: >- Indica se uma solicitação de parada pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do dispatch. stop_requested_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' description: >- Momento em que uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado. created_at: type: string description: Timestamp UTC ISO-8601 format: date-time started_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Timestamp UTC ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- 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. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata additionalProperties: false result_url: type: string description: >- Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use-o com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run individual nativo. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata - action - result_status - missing_formats - error - runs - result_url additionalProperties: false ValidationFailedEncoded: type: object properties: error: type: object properties: code: type: string enum: - validation_failed message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyKeyRequiredEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_key_required message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false UnauthorizedEncoded: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false InsufficientBalanceEncoded: type: object properties: error: type: object properties: code: type: string enum: - insufficient_balance message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false EndpointNotPermittedEncoded: type: object properties: error: type: object properties: code: type: string enum: - endpoint_not_permitted message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ForbiddenEncoded: type: object properties: error: type: object properties: code: type: string enum: - forbidden message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyConflictEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_conflict message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false RateLimitedEncoded: type: object properties: error: type: object properties: code: type: string enum: - rate_limited message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ServiceUnavailableEncoded: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false securitySchemes: bearer: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.