Data API

Referencia de la API

Cada endpoint con la respuesta exacta que devuelve. Una clave, una URL base, un mismo formato de respuesta y un ejemplo real en cada fila.

URL base
https://pinlyx.com/data-api/v2
Versión
2.0.0
Endpoints
127
Plataformas
7

Cómo funciona una llamada

Cuatro cosas que debes saber antes de la primera solicitud. Todo lo que viene después amplía alguna de ellas.

  1. 01

    Obtén una clave

    Se genera en el panel en un minuto, sin tarjeta. Cada clave lleva los permisos que permite tu plan y un nivel de cuota, y es una credencial de servidor a servidor.

  2. 02

    Elige catálogo o en vivo

    La mayoría de los endpoints leen nuestro propio catálogo: rápido, en caché y por una unidad de presupuesto. Los endpoints en vivo consultan la plataforma en ese momento, cuestan más y lo indican con la etiqueta En vivo.

  3. 03

    Lee el formato de respuesta

    Una respuesta correcta siempre trae data y meta. Un fallo siempre trae un objeto error con un código estable. La estructura nunca cambia de un endpoint a otro.

  4. 04

    Vigila las cabeceras

    Cada respuesta te dice en qué punto estás: los límites por minuto y diarios de tu nivel y el presupuesto del plan que contrataste. Nada se agota sin avisar.

Autenticación

Cada solicitud necesita una clave. Envíala como token bearer, o como x-api-key si le va mejor a tu cliente. Las claves se generan en el panel y son credenciales de servidor a servidor: cualquiera que abra las herramientas de desarrollo en una página que la contenga tendrá toda tu cuota.

# Preferred: bearer token
curl https://pinlyx.com/data-api/v2/accounts/instagram/nasa \
  -H "Authorization: Bearer psk_live_..."

# Equivalent: plain header
curl https://pinlyx.com/data-api/v2/accounts/instagram/nasa \
  -H "x-api-key: psk_live_..."
Formato de la clave. psk_live_... for production keys, psk_test_... for test keys

Keys are server-to-server credentials. Never embed one in front-end code - call the API from your own backend and forward the result.

Anatomía de una respuesta

Una respuesta real de GET /accounts/{platform}/{handle}, tal como la devuelve la API. data es la respuesta. meta es el recibo: quién la sirvió, cuánto tardó y qué antigüedad tiene el dato.

GET /accounts/instagram/nasa
{
  "data": {
    "platform": "instagram",
    "handle": "nasa",
    "checked_at": "2026-08-30T09:14:02.113Z",
    "exists": true,
    "evidence": "catalog",
    "identity": {
      "id": "528817151",
      "handle": "nasa",
      "name": "NASA",
      "avatar_url": "https://scontent.cdninstagram.com/v/t51.2885-19/...",
      "url": "https://www.instagram.com/nasa/",
      "object": "account"
    },
    "audience": {
      "count": 104443318,
      "metric": "followers",
      "precision": "exact"
    },
    "flags": {
      "verified": true,
      "private": false,
      "nsfw": false
    },
    "created_at": null,
    "catalog": {
      "state": "present",
      "status": "active",
      "tier": "a",
      "category": "science",
      "language": "en",
      "country": null,
      "last_seen": "2026-08-30T04:02:11.000Z",
      "data_age_s": 18711,
      "directory_url": "/best-instagram-accounts/nasa",
      "metrics": {
        "engagement_rate": 0.4213,
        "avg_likes": 402118,
        "avg_comments": 2904,
        "posts_analyzed": 12,
        "citation_score": 91
      }
    }
  },
  "meta": {
    "request_id": "req_9f2c41a8b3d5",
    "generated_at": "2026-08-23T09:14:02.317Z",
    "took_ms": 42
  }
}

El bloque data

Su forma depende del endpoint y está documentada en cada fila de abajo. En los endpoints de cuentas, cada recuento es un número o null, y null significa que no se midió, nunca cero.

El bloque meta

  • request_idstringobligatorio

    Unique id for this request. Quote it in a support ticket.

  • generated_atstringobligatorio

    Server time the response was produced.

  • took_msintegerobligatorio

    Milliseconds spent server-side.

  • pagePageopcional
  • sourcestringopcional

    Which backend served the payload, for endpoints with more than one.

  • cache_age_sintegeropcional

    Age of the underlying data in seconds. 0 for live reads.

El formato de error

Un fallo nunca trae data. Decide según error.code, que es estable y está enumerado; message es texto libre y puede cambiar. details aparece en invalid_request e indica los campos con problemas.

422
{
  "error": {
    "code": "invalid_request",
    "message": "One or more parameters are invalid.",
    "details": {
      "limit": "Must be between 1 and 500."
    },
    "request_id": "req_9f2c41a8b3d5"
  }
}

Catálogo o en vivo

La única decisión que tomas en cada llamada: leer lo que ya tienen nuestros rastreadores o preguntar a la plataforma en este mismo segundo.

Lecturas del catálogo

  • Se sirven desde nuestra propia base de datos: una consulta al índice, milisegundos.
  • Cuestan una unidad de presupuesto y solo cuentan para los límites por minuto y diarios de tu nivel.
  • meta.cache_age_s indica la antigüedad del dato, así que la frescura se comprueba en el código, no se adivina.
  • 45 de 127 endpoints.

Lecturas en vivo

  • Consultan la plataforma en el momento de la solicitud y devuelven cache_age_s = 0.
  • Se miden contra una cuota aparte de llamadas en vivo por minuto y cuestan más de una unidad de presupuesto; el multiplicador figura en cada plan.
  • 15 de ellos también gastan créditos externos en cada llamada y llevan la etiqueta Consume créditos.
  • 45 endpoints en total, cada uno con la etiqueta En vivo en su fila de abajo.

Paginación

Los endpoints de listas aceptan ?limit= (hasta 500) y ?cursor=. Sigue meta.page.next_cursor hasta que sea null; una página corta no significa que se haya terminado. Los cursores son opacos y van firmados, así que la paginación se mantiene coherente mientras se insertan filas, y un cursor escrito a mano se rechaza.

GET /directory/x?limit=50
{
  "data": [
    "..."
  ],
  "meta": {
    "request_id": "req_9f2c41a8b3d5",
    "page": {
      "limit": 50,
      "next_cursor": "eyJrIjoiMTczNDU2IiwiZCI6ImEifQ",
      "count": 50
    }
  }
}

meta.page

  • limitintegerobligatorio

    Rows requested. Default 50, maximum 500.

  • next_cursorstringobligatorio

    Pass as ?cursor= to fetch the next page. null means the result set is exhausted, and it is the only reliable stop condition.

  • countintegerobligatorio

    Rows in this page.

  • totalintegeropcional

    Total matching rows. Present only when counting is cheap; never assume it is there.

Permisos

Cada clave lleva un conjunto de permisos y cada endpoint declara exactamente uno. El plan marca el techo: si pides un permiso que tu plan no incluye, se rechaza al crear la clave, no en la primera llamada.

  • directory:read

    Read the account and channel catalog across all seven platforms.

  • scrape:liveSensible

    Read from the platform itself rather than from the catalog: a profile or channel on any of the seven platforms, and on X the whole content layer - timelines, posts, replies, quotes, threads, followers, search, lists and communities.

  • insights:read

    Engagement rates, top posts, viral patterns, cohort benchmarks.

  • research:read

    Findings, runs and events from the autonomous research engine.

  • leads:readSensible

    LinkedIn company and contact data, and X follower-graph exports.

  • tools:useSensible

    Run the analysis tools: valuation, follower audit, scoring, and more.

Los permisos sensibles no se añaden por defecto a una clave nueva, y cada llamada que los usa queda auditada.

Límites de uso y presupuesto del plan

Se aplican dos cuotas a la vez: un máximo de ráfaga por minuto y una cuota diaria, ambas según el nivel que te da tu plan. Los endpoints que consultan una plataforma en vivo tienen su propio límite, así que paginar el catálogo rápido nunca deja sin cuota a las consultas en vivo.

NivelPor minutoPor díaEn vivo por minuto
free3010005
standard12025.00020
pro600250.00060
unlimited600010.000.000600

Los techos de cada nivel son límites técnicos. Lo que contrataste va aparte y se informa en su propia familia de cabeceras, X-Plan-*, que no aparece en una clave que no esté vinculada a una suscripción. El error 429 quota_exceeded se resuelve con el tiempo; el 402 payment_required no: se resuelve cuando pagas el excedente o renuevas.

Cabeceras de límites

  • X-RateLimit-Limit

    Requests allowed in the current one-minute window.

  • X-RateLimit-Remaining

    Requests left in the current one-minute window.

  • X-RateLimit-Reset

    Unix seconds at which the current window resets.

  • X-Quota-Limit

    Requests allowed today, from your tier.

  • X-Quota-Remaining

    Requests left in today's quota.

  • Retry-After

    Seconds to wait before retrying.

  • X-Request-Id

    Unique id for this request, echoed in meta.request_id.

Cabeceras del plan

  • X-Plan

    Plan id behind the key.

  • X-Plan-Limit

    Requests included in the current billing period.

  • X-Plan-Remaining

    Included requests left in the current billing period.

  • X-Plan-Overage

    Requests served beyond the included allowance so far this period.

  • X-Plan-Period-End

    When the current billing period ends, ISO 8601.

Códigos de error

Ocho estados HTTP y catorce códigos: esa es la lista completa. Decide según el código; el estado por sí solo no basta para saber qué hacer.

EstadoCódigosCuándoQué hacer
401
unauthorizedinvalid_key
No key was presented, or the key is unknown, revoked or expired.Revisa la clave y el nombre de la cabecera. Si la clave está revocada o caducada, genera una nueva en el panel.
402
payment_requiredsubscription_inactive
The key is valid but the plan behind it cannot serve the call: the included requests are spent and overage is switched off, capped or unfunded (payment_required), or the billing period lapsed and was not renewed (subscription_inactive). Retrying does not help; paying does. The X-Plan-* headers on this response say how far past the line you are.Paga el excedente o renueva el periodo en el panel. Reintentar no sirve de nada.
403
forbidden_scopeforbidden_ip
The key is valid but not allowed to make this call: it lacks the scope, or the request came from an address outside the key's allowlist.Pide el permiso al crear la clave o añade la dirección de quien llama a la lista de direcciones permitidas de la clave.
404
not_found
The addressed resource does not exist.Revisa el usuario o el id. En los endpoints de cuentas, una cuenta que aún no hemos indexado no da 404; consulta catalog.state.
422
invalid_request
A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.Lee error.details: indica cada parámetro incorrecto y el rango en el que debería estar.
429
rate_limitedquota_exceeded
Either the burst ceiling for the current minute or the daily quota is spent. Distinguish with the code: rate_limited clears within the minute, quota_exceeded does not clear until 00:00 UTC.Espera los segundos de Retry-After. rate_limited se resuelve en menos de un minuto; quota_exceeded, a las 00:00 UTC.
500
internal_error
Something failed on our side. Internals are never leaked; quote the request id.Reintenta una vez y, si sigue fallando, contacta con soporte indicando el request_id.
503
upstream_timeoutupstream_errornot_configured
The request could not be served right now. BRANCH ON error.code, not on the status: 'upstream_timeout' means a source was too slow (this is what a catalog query hitting its 15-second statement timeout returns, so it is reachable from any endpoint that reads the corpus, not only the live-scrape ones) and the same call is worth retrying with backoff - narrowing it with a smaller limit, a filtered scope or a less popular account makes it far less likely; 'upstream_error' means a source was unreachable, so back off further; 'not_configured' means the capability has no backing service in this deployment, and retrying will never help.Reintenta con espera progresiva en upstream_timeout y upstream_error; una consulta más acotada ayuda. not_configured no se resuelve nunca.

Endpoints

Agrupados como los agrupa la API. Abre una fila para ver sus parámetros, una solicitud lista para copiar y la respuesta que devuelve.

Cada endpoint tiene su propia páginaEl índice completo, agrupado y enlazable: método, ruta y qué responde cada llamada, con una página por endpoint que incluye sus parámetros, un cuerpo de respuesta real y sus códigos de error.
127 de 127 endpoints

Accounts5

Check one account, on any of the seven platforms, in one shape: does it exist, how big is it, is it verified, when was it created, is it in our catalog and how stale is that reading. The catalog checks are index probes and cost nothing; add /live to read the platform itself.

Página completa
Página completa
Página completa
Página completa
Página completa

Directory9

The account and channel catalog the crawlers maintain across X, Instagram, TikTok, YouTube, Telegram and Bluesky. Reads are served from our own Postgres, so they are fast, cheap and bounded only by your tier.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

X25

The raw X (Twitter) surface, read live: profiles, timelines, followers and following, single posts with their replies, quotes, reposts and full threads, advanced search, list timelines and community feeds. Where Insights answers how an account is performing off our own catalog, this group answers what X says right now - and it is the one place the post layer itself is published rather than measured. Every call spends a slot on a finite scraper pool, so it is metered as a live call and paginated with cursors rather than offsets.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

People2

Cross-catalog people search: one handle looked up in every catalog at once, or accounts matched by audience size, engagement, language and category across platforms.

Página completa
Página completa

Live scrape5

On-demand reads that skip the catalog and fetch from the source right now. Slower and separately metered, because every call costs upstream work. Reach for these when you need one handle fresh, not for bulk enrichment.

Página completa
Página completa
Página completa
Página completa
Página completa

Insights32

Derived engagement intelligence: engagement rates, top and viral posts, posting patterns and cohort benchmarks computed over the post layer.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

Identity5

The same entity seen from more than one place: the social accounts a company publishes, the company behind a handle, and the several usernames a Telegram channel can hold at once. Every other surface here describes an account you already identified; this one closes the loop between an organisation and its presence.

Página completa
Página completa
Página completa
Página completa
Página completa

Graph4

The X follow graph: audience overlap between two accounts, lookalike accounts by shared audience, and an account's followers ranked by their own influence.

Página completa
Página completa
Página completa
Página completa

Watch10

Webhooks. Register a destination, prove you control it, watch accounts for audience change, and read or replay every delivery.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

Research4

Findings, runs and events from the autonomous research engine, which decides on its own which pools to expand and reports what it learned.

Página completa
Página completa
Página completa
Página completa

Tools18

The analysis tools behind the public free-tool pages, callable directly: valuation, follower audit, scoring and the rest. Metered like a live call, because each run costs compute or an upstream fetch.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

Leads6

B2B lead data: LinkedIn companies and decision makers, plus X follower-graph exports. Sensitive by nature, separately scoped, and never granted by default.

Página completa
Página completa
Página completa
Página completa
Página completa
Página completa

pinlyx.com/data-api

Empieza con el plan gratis

Cien solicitudes, una clave y sin tarjeta. Suficiente para comprobar que los datos son los que necesitas antes de pagar nada.