> ## 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. # Investigación web > Busca en la web, noticias, lugares y otro contenido público, recupera una página u obtén una respuesta con fuentes. Elige una acción y proporciona una consulta o URL como se describe a continuación. Cada acción devuelve `output` normalizado; consulta `result_status` para conocer la entrega. News, places, scholar, shopping, images, videos y similares exponen `output.items[]` con campos fijos por fila; answer expone `output.answer` y `citations[]`. Scrape expone `text`, `markdown`, `html` y `raw_html`; los formatos ausentes son null. La salida nativa del proveedor no se repite en `output`; permanece en el Run y puede leerse con [Get Run](https://glasser.ai/docs/es/api-reference/runs/get.md). Glasser no convierte HTML en texto ni juzga la calidad semántica según la redacción o la longitud. Search devuelve `output.results[]` y admite `time_range: day | week | month | year`. Una respuesta vacía pero válida es `no_result` y conserva la estructura de la acción: `results` o `items` es `[]`, y una respuesta vacía es `answer: null` con `citations: []`. Scrape no tiene respuesta vacía: una página que no se puede entregar es `error`, con `output: null` y el motivo en `error.code`. Fetch (`scrape`) usa Serper y luego Firecrawl dentro de un presupuesto de solicitud predeterminado de 30 segundos. HTML o las solicitudes explícitas de antigüedad de caché van directamente a Firecrawl. El enriquecimiento de X/Twitter y LinkedIn excluye Firecrawl. Un proveedor especificado por nombre nunca recurre a una alternativa. Una salida vacía o no válida, errores del proveedor, un tiempo de espera agotado o la ausencia de formatos compatibles pueden activar el fallback. El contenido entregado proviene del Run final; no se combina contenido de capturas diferentes. `charge_usd` totaliza `runs` de esta respuesta, incluidos los fallos facturables y los resultados vacíos, y es null hasta que todos los Runs se resuelvan. El ciclo de vida del Run final permanece en `status`; `COMPLETED` por sí solo no demuestra la entrega de contenido. Para trabajos pendientes, sigue el [result\_url](https://glasser.ai/docs/es/api-reference/solutions/gtm/web_research/result.md) autenticado para conservar la salida normalizada y los cargos totales. [Get Run](https://glasser.ai/docs/es/api-reference/runs/get.md) sigue siendo nativo e informa de un cargo individual. El sondeo no crea Runs ni reanuda el fallback. Un reintento POST intencional usa la misma Idempotency-Key y los mismos parámetros de ejecución, reutiliza los Runs existentes e inicia una nueva ventana de solicitud. Consulta [Provider selection and charges](https://glasser.ai/docs/es/api-reference/solutions/overview.md#how-provider-selection-works). ## Salida por acción Cada campo está presente en todas las filas; un valor que el proveedor no informa es `null`. Los campos siguen las [convenciones de campos](https://glasser.ai/docs/es/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` es una marca de tiempo UTC ISO 8601, que se completa únicamente cuando el proveedor informa de una marca de tiempo de máquina (Exa `publishedDate`, noticias de SerpApi `iso_date`). `fetched_at` tiene el mismo formato. * `date_text` es exactamente el texto mostrado por Google tal como se devuelve. Puede ser relativo al `completed_at` del Run ("hace 3 horas") y nunca se analiza. * search `date` está obsoleto: contiene el texto mostrado por Google para Serper y SerpApi, y el `publishedDate` sin procesar de Exa para Exa. Usa `published_at` o `date_text`. * `snippet` es el extracto breve de Google o el resaltado extraído de Exa para Exa; nunca es el texto completo de la página. * `price_text` y `duration_text` son cadenas mostradas, no analizadas; la moneda del precio sigue a `country`. * `rating` es el promedio de estrellas de Google, de 1 a 5, y `reviews` es un recuento. `source` es el nombre del editor o del sitio. * `address` es el texto propio del proveedor; Serper puede devolver únicamente la línea de la calle. * `exa_similarity_score` es la puntuación propia de Exa, comparable únicamente dentro de una misma respuesta. Similar excluye las páginas del host de la URL solicitada. * `text_character_limit` es el límite de caracteres que Glasser solicitó aplicar al proveedor (10000 para Exa); el texto de exactamente esa longitud puede estar truncado. `cached` indica si el proveedor sirvió la página desde su caché. * `quality` siempre es `unverified` y se eliminará en la próxima revisión incompatible. ```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.es.json post /v1/solutions/gtm/web_research openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: >- Una API Key, sin contrato, con pago por llamada, para APIs de pago adquiridas al por mayor. Cada respuesta incluye x-request-id; cada cuerpo de error incluye el mismo sobre. 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: Investigación web description: >- Busca y recupera contenido web público. Cada acción devuelve un resultado normalizado con el id, el proveedor de datos y el estado del ciclo de vida del último Run: search proporciona output.results[]; news / places / scholar / shopping / images / videos / similar proporcionan output.items[] con campos fijos por fila; answer proporciona output.answer y citations[]; y scrape proporciona campos de contenido fijos. Para scrape, lee output.text, output.markdown, output.html y output.raw_html. Los formatos faltantes son null; no se realiza ninguna conversión de HTML a texto. El resultado nativo del proveedor de datos no se repite en output; léelo del Run con GET /v1/runs/:id. Para search, lee output.results[]. Lee result_status por separado de status: success, partial, no_result, error o pending. COMPLETED significa que el Run final terminó con una respuesta del proveedor de datos; no demuestra que el contenido sea utilizable. output es null si falla la entrega o mientras está pending. partial enumera missing_formats. La semántica del contenido no está verificada; la redacción ni la longitud del texto determinan su calidad. charge_usd es el total de los Runs de esta respuesta, incluidos los fallos de pago y los resultados vacíos. Es null hasta que todos los Runs enumerados hayan terminado. runs[] contiene los cargos individuales, los estados y charge_basis, sin cuerpos duplicados. El total de varios Runs tiene charge_basis=null. La respuesta es un resultado de Solution, no el Run almacenado. GET /v1/runs/:id sigue siendo nativo y tiene un cargo individual. Para QUEUED/RUNNING (HTTP 202), consulta periódicamente result_url autenticado en el origen de la API. Esa lectura devuelve el mismo contrato normalizado y el total, no crea Runs y no reanuda el fallback. Los resultados terminales devuelven HTTP 200, incluidos los errores de negocio; inspecciona result_status y error. Reutiliza el mismo Idempotency-Key y los parámetros de ejecución para un reintento intencional. Scrape usa automáticamente Serper y luego Firecrawl dentro de un presupuesto de solicitud predeterminado de 90000 ms. Cada llamada al proveedor de datos comienza con la ventana de su Endpoint; cuando esa ventana excedería el presupuesto de la solicitud, Serper, Firecrawl y Exa usan el tiempo restante real y reservan tiempo para la liquidación y la respuesta. HTML o una antigüedad de caché explícita se envían directamente a Firecrawl. El enriquecimiento de X/Twitter y LinkedIn excluye Firecrawl; Exa y DataForSEO solo se usan de forma explícita. Un proveedor de datos nombrado nunca hace fallback. Un resultado vacío o no válido, errores del proveedor de datos, tiempos de espera y formatos compatibles faltantes pueden activar el fallback cuando otra ruta pueda mejorar la entrega. No se combinan contenidos entre proveedores de datos. Si no se admite ningún Run, devuelve el error de admisión. Cuando se omite formats, Serper/Exa comprueban text y Firecrawl/DataForSEO comprueban markdown; todos los formatos nativos disponibles se asignan a output. max_charge_usd cubre todos los Runs de esta solicitud, incluidas las reproducciones. Los presupuestos solo se mantienen en la memoria de la solicitud; reintentar inicia una nueva ventana de tiempo, pero no puede cambiar el plazo existente de un Run. Search time_range admite day, week, month y year. Auto selecciona un proveedor de datos que admita el filtro. Los resultados de búsqueda vacíos no activan un fallback de pago. operationId: gtm-web-research parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- Genera un valor único para cada ejecución prevista (se recomienda un UUID). Reintenta con la misma clave y los mismos parámetros de ejecución para recuperar el Run original sin un segundo cargo. Cambiar los parámetros de ejecución con la misma clave devuelve 409; cambiar task_id o metadata no actualiza el 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: >- Predeterminado: search. - Proporciona query para search, news, places, scholar, shopping, images, videos o answer. - Proporciona url para scrape o similar. - type: 'null' provider: anyOf: - type: string enum: - auto - serper - serpapi - exa - dataforseo - firecrawl description: >- Predeterminado auto: selecciona el primer proveedor de datos elegible según el orden de preferencia de Glasser. Un proveedor de datos nombrado debe admitir la solicitud y estar permitido por tu Key; no hace fallback a otro proveedor de datos. Los valores disponibles se indican a continuación. - 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: >- Solo para scrape. Cuando se omite, usa el valor predeterminado nativo del proveedor de datos seleccionado: text para Serper/Exa, markdown para Firecrawl/DataForSEO. Los formatos solicitados orientan el enrutamiento y el fallback; output expone los campos fijos text/markdown/html/raw_html. html significa HTML limpiado; raw_html significa HTML original. Auto usa Serper y luego Firecrawl. Las solicitudes HTML se envían directamente a Firecrawl. Lee result_status y missing_formats para comprobar la entrega; un campo null no solicitado no es un resultado parcial. Firecrawl no proporciona text; Glasser no convierte HTML a texto. X/Twitter y las rutas de enriquecimiento están excluidas de Firecrawl. timeout_ms: type: integer minimum: 1000 maximum: 120000 description: >- Solo para scrape. Predeterminado: 90000. Presupuesto de ejecución para esta solicitud de API, incluido el fallback secuencial. Cada llamada al proveedor de datos comienza con la ventana de su Endpoint, en lugar de una parte del tiempo restante; conserva la ventana completa cuando esta, junto con el tiempo de liquidación, cabe en el presupuesto restante. Cuando la ventana completa excedería el presupuesto de la solicitud, Serper, Firecrawl y Exa usan el tiempo restante real hasta el límite de la ventana de su Endpoint y reservan tiempo para la liquidación y la respuesta; solo se omite un paso cuando queda menos de 1 segundo de tiempo de llamada. Un reintento inicia una nueva ventana de solicitud y reutiliza los Runs existentes mediante la idempotencia del Run. max_charge_usd: type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, una única escritura canónica). Suma con aritmética decimal o escala por 10^6; nunca uses números de coma flotante. allOf: - pattern: ^\d{1,12}\. description: >- Solo para scrape. Cargo total máximo de los Runs de esta solicitud, incluidos los Runs reproducidos. Antes de crear un Run, los Cargos liquidados más su Cargo máximo deben caber en el límite. Un Run no liquidado detiene el fallback. Omítelo si no quieres establecer un límite del llamador; 0.00 no permite nuevos Runs de pago. cache_max_age_seconds: type: integer minimum: 0 maximum: 2592000 description: >- Solo para scrape. Antigüedad máxima de la caché del proveedor de datos; 0 requiere una consulta en tiempo real. Se excluyen las rutas sin este control. Auto selecciona Firecrawl (milisegundos); Exa explícito recibe horas enteras redondeadas hacia abajo. Los metadatos de caché/consulta desconocidos siguen siendo null. time_range: type: string enum: - day - week - month - year description: >- Solo para search: restringe los resultados al último día, semana, mes o año mediante el filtro de tiempo de Google. Omítelo para cualquier momento. Auto usa solo proveedores de datos que admiten este filtro (Serper y SerpApi). Exa se rechaza cuando se proporciona este campo. Es un filtro del motor de búsqueda, no una fecha de publicación verificada. country: anyOf: - type: string minLength: 2 maxLength: 60 description: >- País para acciones de tipo search, como código ISO de dos letras o nombre del país. Predeterminado: us. No se aplica a scrape ni similar. Se rechaza con 400 cuando el proveedor de datos nombrado no puede aplicarlo. - type: 'null' language: anyOf: - type: string pattern: ^[A-Za-z]{2}$ description: >- Idioma para acciones de tipo search, con dos letras como en, de. No se aplica a scrape ni similar. - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: >- Filas que se devolverán. Mantén un número reducido: la regla de cargo del endpoint enrutado puede leerlo. Cada capacidad aplica además su propio límite. - type: 'null' task_id: anyOf: - type: string description: >- Agrupa los Runs relacionados, incluido el fallback automático, bajo un único Task. Reutiliza una cadena estable y filtra la lista de Runs por task para recuperarlos. - 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 opcionales de seguimiento, devueltos en el Run y disponibles como filtros. Nunca se envían al proveedor de datos ni afectan al enrutamiento, al Price o a la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. Las entradas no válidas se descartan por completo, no se truncan. La solicitud continúa y el Run devuelve los campos que se almacenaron. - type: 'null' additionalProperties: false required: true responses: '200': description: Éxito content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebResearchResult' '202': description: Éxito 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: No autorizado content: application/json: schema: $ref: '#/components/schemas/UnauthorizedEncoded' '402': description: InsufficientBalance content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: EndpointNotPermitted | Forbidden 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: Servicio no disponible content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableEncoded' security: - bearer: [] components: schemas: WebResearchResult: type: object properties: id: type: string run_url: type: string description: Abre este Run en la consola. Requiere pertenecer al 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 o RUNNING: todavía está en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no son 2xx. FAILED: consulta `failure`. STOPPED: se detuvo antes del dispatch. Lee charge_usd por separado del estado. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: >- Motivo por el que falló el Run. No es null solo cuando el estado es FAILED. input: type: object output: anyOf: - anyOf: - type: object properties: url: type: string description: >- La URL solicitada o la URL final cuando el proveedor de datos informa de una. final_url: anyOf: - type: string - type: 'null' description: >- La URL posterior a la redirección según la informa el proveedor de datos (Firecrawl, Exa). Null cuando el proveedor de datos no informa de ninguna. 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: >- Límite de caracteres que Glasser solicitó al proveedor de datos para el texto (10000 para Exa), por lo que el texto de exactamente esta longitud puede estar truncado. Null cuando no se aplicó ningún límite. cached: anyOf: - type: boolean - type: 'null' description: >- Indica si el proveedor de datos sirvió la página desde su caché (cacheState de Firecrawl, source de status de Exa). Null cuando el proveedor de datos no lo indica. fetched_at: anyOf: - type: string - type: 'null' description: >- Momento en que el proveedor de datos obtuvo la página, UTC ISO 8601 (fetch_time de DataForSEO). Null cuando el proveedor de datos no lo informa. quality: type: string enum: - unverified description: >- Obsoleto: siempre 'unverified'; no se comprueba el contenido. Se conserva por compatibilidad y se eliminará en la próxima revisión incompatible. 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: >- Extracto breve de Google (Serper / SerpApi) o fragmento destacado extraído por Exa para Exa. No es el texto completo de la página. position: type: integer date: anyOf: - type: string - type: 'null' description: >- Obsoleto: usa published_at o date_text. Contiene el texto mostrado por Google para Serper / SerpApi y el publishedDate sin procesar de Exa para Exa. published_at: anyOf: - type: string - type: 'null' description: >- Marca de tiempo UTC ISO 8601, cumplimentada solo cuando el proveedor de datos informa de una marca de tiempo de máquina (publishedDate de Exa, iso_date de noticias de SerpApi); de lo contrario, null. date_text: anyOf: - type: string - type: 'null' description: >- Texto mostrado por Google exactamente como lo devolvió el proveedor de datos (fecha de Serper / SerpApi). Puede ser relativo a completed_at del Run, como '3 hours ago', y nunca se analiza. 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: >- Nombre del editor o del sitio tal como lo muestra el proveedor de datos. published_at: anyOf: - type: string - type: 'null' description: >- Marca de tiempo UTC ISO 8601, cumplimentada solo cuando el proveedor de datos informa de una marca de tiempo de máquina (publishedDate de Exa, iso_date de noticias de SerpApi); de lo contrario, null. date_text: anyOf: - type: string - type: 'null' description: >- Texto mostrado por Google exactamente como lo devolvió el proveedor de datos (fecha de Serper / SerpApi). Puede ser relativo a completed_at del Run, como '3 hours ago', y nunca se analiza. 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 de dirección del proveedor de datos, sin analizar ni completar. Serper puede devolver solo la línea de la calle. category: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Valoración media de Google mediante estrellas, de 1 a 5. reviews: anyOf: - type: integer - type: 'null' description: >- Número de reseñas de Google en las que se basa la valoración. 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 de Google Maps del lugar (cid de Serper, data_cid de 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: Página del producto en Google Shopping. merchant_url: anyOf: - type: string - type: 'null' description: >- URL de la oferta del comerciante cuando la informa el proveedor de datos (link de SerpApi); null para Serper. google_product_id: anyOf: - type: string - type: 'null' description: >- ID del producto del catálogo de Google Shopping (productId de Serper, product_id de SerpApi). price_text: anyOf: - type: string - type: 'null' description: >- Precio mostrado por el proveedor de datos, como '$69.00'. No se analiza; la moneda depende del país. seller: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Valoración media de Google mediante estrellas, de 1 a 5. reviews: anyOf: - type: integer - type: 'null' description: >- Número de reseñas de Google en las que se basa la valoración. 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: >- Nombre del editor o del sitio tal como lo muestra el proveedor de datos. 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 tal como la muestra el proveedor de datos, como YouTube. date_text: anyOf: - type: string - type: 'null' description: >- Texto mostrado por Google exactamente como lo devolvió el proveedor de datos (fecha de Serper / SerpApi). Puede ser relativo a completed_at del Run, como '3 hours ago', y nunca se analiza. duration_text: anyOf: - type: string - type: 'null' description: >- Duración mostrada tal como se devolvió, 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: >- Puntuación de similitud propia de Exa para esta página. Compárala solo dentro de una misma respuesta; no es comparable con las puntuaciones de otros proveedores de datos. published_at: anyOf: - type: string - type: 'null' description: >- Marca de tiempo UTC en formato ISO 8601, rellenada solo cuando el proveedor de datos informa de una marca de tiempo generada por máquina (Exa publishedDate, SerpApi news iso_date); de lo contrario, 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: >- Marca de tiempo UTC en formato ISO 8601, rellenada solo cuando el proveedor de datos informa de una marca de tiempo generada por máquina (Exa publishedDate, SerpApi news iso_date); de lo contrario, null. required: - url - title - published_at additionalProperties: false required: - answer - citations additionalProperties: false - type: 'null' description: >- Campos normalizados por acción. El resultado nativo del proveedor de datos no se repite aquí; permanece en el Run (GET /v1/runs/:id). Los valores que el proveedor de datos no informa son null. - search: results[]: url, title, snippet (extracto de Google; fragmento extraído de Exa para Exa), position, published_at, date_text, date (obsoleto) - news: items[]: title, url, source, published_at, date_text, snippet - places: items[]: name, address (texto del proveedor de datos; puede ser solo la línea de la calle), 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 de 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 está en formato ISO 8601 UTC y solo se establece a partir de la marca de tiempo generada por máquina del proveedor de datos. date_text es el texto mostrado por Google tal como se devuelve; puede ser relativo a completed_at del Run y nunca se analiza. rating es el promedio de estrellas de Google de 1–5; reviews es un recuento. source es el nombre del editor o sitio. exa_similarity_score es la puntuación propia de Exa y solo se puede comparar dentro de una misma respuesta. provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté COMPLETED. error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: >- No es null únicamente cuando el estado es COMPLETED. - Para respuestas 2xx, output contiene el JSON nativo del proveedor de datos (de cualquier estructura), o null si el cuerpo está vacío. - Para respuestas que no sean 2xx, error contiene el cuerpo de error del proveedor de datos y output es null. Los campos confidenciales se eliminan de ambos cuerpos. charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, una única representación canónica). Suma mediante aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo total de los Runs de esta respuesta de Solution. Es null hasta que se establezcan todos los Runs enumerados. Cada Run conserva su propio cargo; los fallos también pueden generar cargos. 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 del cargo de un solo Run, o null para un total de varios Runs. Lee runs[].charge_basis para cada cargo. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. No garantiza que el Run pueda detenerse antes del dispatch. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el dispatch ya había comenzado. created_at: type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC en formato 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: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final; nunca su dirección de correo electrónico ni su nombre. 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: >- Estado de entrega empresarial, independiente del ciclo de vida final del Run en status. success no es un veredicto semántico sobre la calidad del contenido. 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: >- Abre este Run en la consola. Requiere pertenecer a un 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 o RUNNING: todavía está en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no sean 2xx. FAILED: consulta `failure`. STOPPED: detenido antes del dispatch. Consulta charge_usd por separado 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 por el que falló el Run. Solo es distinto de null cuando status es 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: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté 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: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, una única representación canónica). Suma mediante aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo final como cadena decimal exacta en USD. Es null mientras esté QUEUED o RUNNING. Un Run FAILED puede tener un cargo distinto de cero según el Price del 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 Price utilizada para calcular el cargo. Es null antes de la liquidación o cuando no se realizó ningún intento con el proveedor de datos. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. No garantiza que el Run pueda detenerse antes del dispatch. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el dispatch ya había comenzado. created_at: type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC en formato 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: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final; nunca su dirección de correo electrónico ni su nombre. 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: >- Ruta URL autenticada y de solo lectura para consultar este resultado normalizado y el cargo total. Úsala con el origen de la API. No crea Runs ni reanuda el fallback. GET /v1/runs/:id sigue devolviendo el 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.