Buscar

POSThttps://api.typesearch.ai/v1/search

Busca en el índice y devuelve las notas relevantes, de más a menos relevante, cada una con un score calibrado. Con varias consultas, los resultados vienen en una sola lista y cada consulta tiene además su propia entrada en groups.

Pon stream: true para recibir Server-Sent Events mientras busca.

Cuerpo

querystring | string[]obligatorio
Una consulta, o hasta cinco que se juzgan juntas en el mismo pedido, más rápido que buscarlas de a una; cada una se cobra como una búsqueda de su modo. De 2 a 200 caracteres cada una.
Elementos: hasta 5
indexstring
Busca en tu propio índice (idx_…) en lugar del índice de noticias: los mismos modos, precios, questions, tone y highlights. Una consulta por pedido, y sin filtro de fechas salvo que indiques uno. Ver la guía del índice propio.
sourcesstring[]
Sólo estas fuentes, por dominio (como diarioejemplo.example), hasta 100. Un dominio que no está en el índice vuelve como aviso domain_not_indexed.
Elementos: hasta 100
include_domainsstring[]
Sólo estos dominios o rutas, hasta 20. Un dominio incluye sus subdominios; una ruta como diarioejemplo.example/economia, todo lo que cuelga de ella.
Elementos: hasta 20
exclude_domainsstring[]
Nunca estos dominios o rutas, hasta 20. Las mismas reglas que include_domains.
Elementos: hasta 20
countriesstring[]
Sólo fuentes con sede en estos países: códigos ISO 3166-1 alfa-2, como AR o US.
Elementos: hasta 50
languagesstring[]
Sólo fuentes que publican en estos idiomas: códigos ISO 639-1, como es o en. Una etiqueta como pt-BR cuenta como pt.
Elementos: hasta 20
sectionsstring[]
Sólo estas secciones: la que declara la fuente, o el primer tramo de la ruta (economia).
Elementos: hasta 20
daysinteger | null
Los últimos N días, de 1 a 365. null busca en todo el índice. Por defecto 7, salvo que se indique published_after o published_before.
Rango: 1–365
published_afterdate | date-time
Publicadas desde este momento. Una fecha sola (2026-09-20) cubre el día entero en UTC−3; una fecha y hora necesita la zona.
published_beforedate | date-time
Publicadas hasta este momento, inclusive. El mismo formato que published_after.
modeenum<string>Por defecto: "normal"
ultra juzga sólo titulares y es el más barato · fast juzga titulares y bajadas · normal además lee los mejores resultados para confirmarlos · deep juzga todo el índice y lee más.
max_resultsintegerPor defecto: 10
Cuántos resultados devolver, de 1 a 50.
Rango: 1–50
highlightsboolean
Devuelve un fragmento textual breve de las notas leídas: como mucho uno por nota (dos en deep), de hasta 25 palabras y nunca del primer párrafo. Por defecto true en deep y false en los demás.
dedupebooleanPor defecto: false
Agrupa la misma noticia contada por varios medios en un solo resultado, con los demás en duplicates.
tonebooleanPor defecto: false
Clasifica cada resultado como positivo, neutral o negativo respecto de la consulta, y lo resume por fuente.
essentialboolean
Devuelve hasta tres fragmentos textuales de fuentes distintas que resumen la noticia, con los mismos límites que highlights. Por defecto true en deep.
questionsmapa<string, …>
Salida estructurada: hasta 8 preguntas tipadas (boolean, choice o score) respondidas sobre cada resultado, con el nombre que elijas.
max_tokensinteger | null
Un tope de tokens del modelo para el pedido, mínimo 2000. Si se alcanza, recibes todo lo juzgado hasta ahí con incomplete: true.
Rango: 2000–9007199254740991
freshbooleanPor defecto: false
Ignora la caché de resultados. Si no, un pedido idéntico dentro de los 10 minutos sale de la caché sin costo.
temporalenum<string>Por defecto: "auto"
auto: a date in the query («today», «yesterday», «tomorrow», «on September 22», «this week») is taken out of the topic, sets the publication window (unless published_after/before are given; days only bounds it) and puts the results from that day first · off: the query is taken literally.
Uno de: auto · off
timezonestring
IANA time zone that decides what day «today» is. Defaults to Argentina (America/Argentina/Buenos_Aires).
streambooleanPor defecto: false
Envía Server-Sent Events mientras busca: step, partial y un result final.

Respuesta

idstring
El id del pedido; también llega en el encabezado X-Request-Id.
objectenum<string>
search, site_search o similar.
modeenum<string>
El modo que se usó.
Uno de: ultra · fast · normal · deep
queriesstring[]
Las consultas que se buscaron.
foundboolean
Si alguna nota alcanzó el umbral de relevancia (un score de 0,5).
totalinteger
Cuántas notas relevantes se encontraron. Puede ser más que los resultados devueltos.
Rango: -9007199254740991–9007199254740991
resultsobject[]
Los resultados, de más a menos relevante.
Ver los campos
- urlstring
  La URL canónica de la nota.
- titlestring
  El titular, de hasta 240 caracteres.
- sourcestring | null
  El medio.
- countrystring | null
  Country of the source (ISO 3166-1 alpha-2), when known.
- languagestring | null
  Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in languages, or its main one.
- published_atstring | null
  La hora de publicación, ISO 8601 en UTC.
- sectionstring | null
  La sección, si la fuente la indica.
- snippetstring | null
  La descripción que el medio le da a la nota en su feed o en los metadatos de la página, de hasta 300 caracteres.
- scorenumber
  Probabilidad calibrada (0–1) de que la nota trate de la consulta: la de la lectura si se leyó, la del titular si no. Entre 0,35 y 0,65 el modelo no se decide.
- headline_relevancenumber
  La probabilidad juzgada sólo por el titular.
- readobject | null
  Presente cuando la nota se abrió y se leyó para confirmarla.
  Ver los campos
  - probabilitynumber
    La probabilidad después de leer la nota.
  - centralitynumber
    Cuán central es la consulta en la nota, de 0 (no aparece) a 3 (el tema principal).
- highlightsstring[]
  Fragmentos textuales sobre la consulta: como mucho uno por nota (dos en deep), de hasta 25 palabras y nunca del primer párrafo. Ninguno en las notas breves.
- toneobject | null
  Presente cuando se pidió tone.
  Ver los campos
  - labelenum<string>
    positive, neutral o negative, respecto de la consulta.
  - probabilitiesmapa<string, number>
    La probabilidad de cada etiqueta.
  - basisenum<string>
    article si se juzgó sobre el texto, headline si no.
- answersobject | null
  Presente cuando se enviaron questions.
  Ver los campos
  - basisenum<string>
    article si se respondió sobre el texto, headline si no.
  - valuesmapa<string, …>
    Una respuesta por pregunta: probability para boolean, choice para choice y score para score, con probabilities y confidence cuando corresponde.
- duplicatesobject[]
  Con dedupe: otros medios que contaron la misma noticia.
  Ver los campos
  - urlstring
    La URL del duplicado.
  - titlestring
    El titular del duplicado.
  - sourcestring | null
    El medio del duplicado.
- date_matchenum<string> | null
  When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
  Uno de: exact · adjacent · unknown · outside
- referenced_datestring | null
  When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
- found_inenum<string>
  Dónde se encontró: index, custom_index si buscaste en tu propio índice, o en un sitio en vivo homepage, section o site_search.
  Uno de: index · homepage · section · site_search · discovery · custom_index
- datamapa<string, string | number> | null
  En búsquedas en un índice propio: los datos estructurados que declara la página, como price, currency, availability, brand o sku. null si no declara ninguno.
- queriesstring[]
  Con varias consultas: a cuáles responde este resultado.
groupsobject[] | null
Con varias consultas: una entrada por consulta, con sus propios resultados y enriquecimientos.
Ver los campos
- querystring
  La consulta.
- foundboolean
  Si esta consulta encontró algo.
- totalinteger
  Notas relevantes para esta consulta.
  Rango: -9007199254740991–9007199254740991
- resultsobject[]
  Los resultados de esta consulta.
  Los mismos campos que results
- near_missesobject[]
  Si no se encontró nada: lo que más se acercó, para que tu agente decida.
  Los mismos campos que results
- rejectedobject[]
  Notas cuyo titular parecía relevante pero que quedaron por debajo de 0,6 al leerlas.
  Los mismos campos que results
- diffusionobject | null
  Cómo se difundió la noticia: notas por día y por fuente, y quién la publicó primero. Sale del índice, sin costo extra.
  Los mismos campos que diffusion
- toneobject | null
  Con tone: conteos por etiqueta, en total y por fuente.
  Los mismos campos que tone
- essentialobject | null
  Con essential: hasta tres fragmentos textuales de fuentes distintas.
  Los mismos campos que essential
- temporalobject | null
  How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
  Los mismos campos que temporal
near_missesobject[]
Si no se encontró nada: lo que más se acercó, para que tu agente decida.
Los mismos campos que results
rejectedobject[]
Notas cuyo titular parecía relevante pero que quedaron por debajo de 0,6 al leerlas.
Los mismos campos que results
diffusionobject | null
Cómo se difundió la noticia: notas por día y por fuente, y quién la publicó primero. Sale del índice, sin costo extra.
Ver los campos
- by_dayobject[]
  Notas por día, en UTC−3.
  Ver los campos
  - daystring
    El día, YYYY-MM-DD.
  - countinteger
    Notas ese día.
    Rango: -9007199254740991–9007199254740991
- by_sourceobject[]
  Notas por fuente, con la hora de la primera de cada una.
  Ver los campos
  - sourcestring
    El medio.
  - countinteger
    Sus notas.
    Rango: -9007199254740991–9007199254740991
  - first_published_atstring
    Cuándo publicó primero.
- firstobject | null
  La primera nota publicada.
  Ver los campos
  - sourcestring | null
    Su medio.
  - urlstring
    Su URL.
  - titlestring
    Su titular.
  - published_atstring
    Cuándo se publicó.
- undatedinteger
  Notas sin fecha de publicación.
  Rango: -9007199254740991–9007199254740991
toneobject | null
Con tone: conteos por etiqueta, en total y por fuente.
Ver los campos
- articlesinteger
  Notas clasificadas.
  Rango: -9007199254740991–9007199254740991
- overallobject
  Conteos por etiqueta.
  Ver los campos
  - positiveinteger
    Notas positivas.
    Rango: -9007199254740991–9007199254740991
  - neutralinteger
    Notas neutrales.
    Rango: -9007199254740991–9007199254740991
  - negativeinteger
    Notas negativas.
    Rango: -9007199254740991–9007199254740991
- by_sourceobject[]
  Conteos por etiqueta, por fuente.
  Ver los campos
  - positiveinteger
    Notas positivas.
    Rango: -9007199254740991–9007199254740991
  - neutralinteger
    Notas neutrales.
    Rango: -9007199254740991–9007199254740991
  - negativeinteger
    Notas negativas.
    Rango: -9007199254740991–9007199254740991
  - sourcestring
    El medio.
essentialobject | null
Con essential: hasta tres fragmentos textuales de fuentes distintas.
Ver los campos
- excerptsobject[]
  Los fragmentos.
  Ver los campos
  - textstring
    El fragmento, textual.
  - urlstring
    La nota de la que sale.
  - sourcestring | null
    Su medio.
  - titlestring
    Su titular.
referenceobject | null
En similar: la nota de referencia.
Ver los campos
- urlstring
  Su URL.
- titlestring
  Su titular.
custom_indexobject | null
Con index: el índice propio en el que se buscó.
Ver los campos
- idstring
  Su id, idx_….
- namestring
  El nombre que le diste.
temporalobject | null
How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
Ver los campos
- expressionstring | null
  The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.
- fromstring | null
  First day of the period the query refers to (YYYY-MM-DD, in timezone).
- tostring | null
  Last day of that period; the same as from for a single day.
- timezonestring
- basisenum<string>
  published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first.
  Uno de: published · event · recency
- windowobject | null
  The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts.
  Ver los campos
  - fromstring
  - tostring
- widenedboolean
  No result is from the requested day: they come from the days around it.
sitestring | null
En site_search: el sitio donde se buscó.
indexobject | null
En búsquedas en el índice: qué tan al día estaba el índice al momento de buscar.
Ver los campos
- updated_atstring | null
  La última vez que se actualizó una fuente.
usageobject
Lo que consumió el pedido.
Ver los campos
- tokensinteger
  Tokens del modelo. 0 si salió de la caché.
  Rango: -9007199254740991–9007199254740991
- callsinteger
  Llamadas al modelo.
  Rango: -9007199254740991–9007199254740991
- cost_usdnumber | null
  Costo en dólares, cuando se conoce.
- headlinesinteger
  Titulares considerados, incluidos los ya juzgados.
  Rango: -9007199254740991–9007199254740991
- from_memoryinteger
  De esos, los que ya se habían juzgado y se reusaron sin costo.
  Rango: -9007199254740991–9007199254740991
- pages_directinteger
  Notas leídas con un pedido simple.
  Rango: -9007199254740991–9007199254740991
- pages_browserinteger
  Páginas abiertas con un navegador.
  Rango: -9007199254740991–9007199254740991
- duration_msinteger
  Tiempo en el servidor, en milisegundos.
  Rango: -9007199254740991–9007199254740991
budgetobject | null
Con max_tokens: el tope, lo usado y si se alcanzó.
Ver los campos
- max_tokensinteger
  El tope que fijaste.
  Rango: -9007199254740991–9007199254740991
- usedinteger
  Tokens usados.
  Rango: -9007199254740991–9007199254740991
- exhaustedboolean
  Si se alcanzó el tope.
discoveryobject | null
El descubrimiento: cuando el índice tiene menos de 3 buenas coincidencias, buscamos fuentes fuera de él y las leemos en el sitio original. null sólo en los eventos parciales, mientras sigue en curso.
Ver los campos
- statusenum<string>
  used: buscó fuera del índice dentro del tiempo disponible · background: en ultra o fast no había nada para revisar rápido; sigue aprendiendo en segundo plano · skipped: el índice alcanzaba, o no corresponde · budget: se llegó al límite del descubrimiento · timeout: se agotó el tiempo (incomplete: true).
- sitesinteger
  Sitios fuera del índice que aportaron candidatos.
  Rango: -9007199254740991–9007199254740991
- msinteger
  El tiempo que sumó a este pedido, en milisegundos.
  Rango: -9007199254740991–9007199254740991
incompleteboolean
true cuando se alcanzó max_tokens o se agotó el tiempo del descubrimiento antes de juzgar todo: puede haber más.
cached_atstring | null
Si salió de la caché: cuándo se calculó el resultado.
warningsobject[]
Avisos que no impiden el pedido, como un dominio que no está en el índice.
Ver los campos
- codestring
  Un código estable.
- messagestring
  Una explicación para personas.

import Typesearch from 'typesearch-js';

const ts = new Typesearch();

const res = await ts.search('el dólar', {
  mode: 'normal',
  max_results: 10,
  include_domains: ['reddiaria.example', 'diarioejemplo.example'],
  published_after: '2026-09-20',
  tone: true,
});

200 OK

{
  "id": "req_8fKq2mZr1xYt",
  "object": "search",
  "mode": "normal",
  "queries": ["el dólar"],
  "found": true,
  "total": 14,
  "results": [
    {
      "url": "https://reddiaria.example/economia/…",
      "title": "El dólar oficial cerró estable en una rueda con poco volumen",
      "source": "Red Diaria",
      "published_at": "2026-09-21T18:05:00.000Z",
      "section": "economia",
      "snippet": "La divisa se mantuvo sin cambios frente al cierre anterior.",
      "score": 0.96,
      "headline_relevance": 0.91,
      "read": { "probability": 0.96, "centrality": 3 },
      "highlights": ["El dólar mayorista terminó la jornada sin variaciones…"],
      "tone": {
        "label": "neutral",
        "probabilities": { "positive": 0.08, "neutral": 0.86, "negative": 0.06 },
        "basis": "article"
      },
      "answers": null,
      "duplicates": [],
      "found_in": "index"
    }
  ],
  "groups": null,
  "near_misses": [],
  "rejected": [],
  "tone": {
    "articles": 14,
    "overall": { "positive": 2, "neutral": 10, "negative": 2 },
    "by_source": []
  },
  "usage": { "tokens": 4210, "calls": 4, "cost_usd": 0.0022, "duration_ms": 2380 },
  "incomplete": false,
  "cached_at": null,
  "warnings": []
}