Data API

Referência da API

Todos os endpoints com a resposta exata que cada um retorna. Uma chave, uma URL base, um envelope e um corpo de exemplo real em cada linha.

URL base
https://pinlyx.com/data-api/v2
Versão
2.0.0
Endpoints
127
Plataformas
7

Como funciona uma chamada

Quatro coisas para saber antes da primeira requisição. Todo o resto mais abaixo detalha uma delas.

  1. 01

    Gere uma chave

    Criada no painel em um minuto, sem cartão. A chave traz os escopos que o seu plano permite e um nível de limites, e é uma credencial de servidor para servidor.

  2. 02

    Escolha catálogo ou ao vivo

    A maioria dos endpoints lê o nosso próprio catálogo: rápido, em cache, uma unidade do orçamento. Os endpoints ao vivo consultam a plataforma na hora, custam mais e avisam isso com o selo Ao vivo.

  3. 03

    Leia o envelope

    O sucesso é sempre data mais meta. A falha é sempre um objeto error com um código estável. O formato nunca muda de um endpoint para outro.

  4. 04

    Fique de olho nos cabeçalhos

    Toda resposta mostra a sua situação: limites de pico e diários do seu nível e o orçamento do plano que você contratou. Nada acaba sem aviso.

Autenticação

Toda requisição precisa de uma chave. Envie como bearer token, ou como x-api-key se isso for mais prático para o seu cliente. As chaves são criadas no painel e são credenciais de servidor para servidor: qualquer pessoa que abrir o devtools em uma página que contenha a chave fica com toda a sua cota.

# 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 da chave. 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.

Anatomia de uma resposta

Uma resposta real de GET /accounts/{platform}/{handle}, exatamente como a API retorna. data é a resposta. meta é o recibo: quem atendeu, quanto tempo levou e qual a idade do número.

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
  }
}

O bloco data

O formato depende do endpoint e está documentado em cada linha abaixo. Nos endpoints de contas, toda contagem é um número ou null, e null significa não medido, nunca zero.

O bloco meta

  • request_idstringobrigatório

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

  • generated_atstringobrigatório

    Server time the response was produced.

  • took_msintegerobrigatório

    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.

O envelope de erro

Uma falha nunca traz data. Tome decisões com base em error.code, que é estável e enumerado; message é texto livre e pode mudar. details aparece em invalid_request e indica os campos com problema.

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 ou ao vivo

A única decisão que você toma em cada chamada: ler o que os nossos crawlers já coletaram ou perguntar à plataforma neste exato segundo.

Leituras do catálogo

  • Atendidas pelo nosso próprio banco de dados: uma consulta ao índice, em milissegundos.
  • Custam uma unidade do orçamento e contam apenas nos limites de pico e diários do seu nível.
  • meta.cache_age_s informa a idade da leitura, então o frescor é uma verificação no código, não um palpite.
  • 45 de 127 endpoints.

Leituras ao vivo

  • Consultam a plataforma no momento da requisição e retornam cache_age_s = 0.
  • São medidas em um limite separado de chamadas ao vivo por minuto e custam mais de uma unidade do orçamento; o multiplicador aparece em todos os planos.
  • 15 delas também consomem créditos do provedor de origem a cada chamada e levam o selo Consome créditos.
  • 45 endpoints no total, cada um com o selo Ao vivo na sua linha abaixo.

Paginação

Os endpoints de listagem aceitam ?limit= (até 500) e ?cursor=. Siga meta.page.next_cursor até ele ser null; uma página curta não significa o fim. Os cursores são opacos e assinados, então a paginação se mantém consistente enquanto novas linhas são inseridas, e um cursor escrito à mão é recusado.

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

meta.page

  • limitintegerobrigatório

    Rows requested. Default 50, maximum 500.

  • next_cursorstringobrigatório

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

  • countintegerobrigatório

    Rows in this page.

  • totalintegeropcional

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

Escopos

Uma chave traz um conjunto de escopos, e cada endpoint declara exatamente um. O plano é o teto: pedir um escopo que o seu plano não inclui é recusado na criação da chave, não na primeira chamada.

  • directory:read

    Read the account and channel catalog across all seven platforms.

  • scrape:liveSensível

    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:readSensível

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

  • tools:useSensível

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

Os escopos sensíveis não vêm em uma chave nova por padrão, e toda chamada feita com eles é auditada.

Limites de taxa e orçamento do plano

Dois limites valem ao mesmo tempo: um teto de pico por minuto e uma cota por dia, ambos definidos pelo nível que o seu plano concede. Os endpoints que consultam uma plataforma ao vivo têm um limite próprio, então paginar o catálogo rapidamente nunca deixa as buscas ao vivo sem capacidade.

NívelPor minutoPor diaAo vivo por minuto
free301.0005
standard12025.00020
pro600250.00060
unlimited6.00010.000.000600

Os tetos de cada nível são limites técnicos. O que você contratou é outra coisa e aparece na sua própria família de cabeçalhos, X-Plan-*, que nem existe em uma chave não vinculada a uma assinatura. O 429 quota_exceeded se resolve com o tempo; o 402 payment_required não: ele só se resolve quando você paga o excedente ou renova o período.

Cabeçalhos de limite

  • 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.

Cabeçalhos do plano

  • 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 erro

Oito status HTTP, quatorze códigos, e esse é o conjunto completo. Decida pelo código: só o status não basta para saber o que fazer.

StatusCódigosQuandoO que fazer
401
unauthorizedinvalid_key
No key was presented, or the key is unknown, revoked or expired.Confira a chave e o nome do cabeçalho. Uma chave revogada ou expirada precisa ser substituída por uma nova no painel.
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.Pague o excedente ou renove o período no painel. Tentar de novo não resolve.
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.Peça o escopo ao criar a chave ou adicione o endereço de quem faz a chamada à lista de permissões da chave.
404
not_found
The addressed resource does not exist.Confira o handle ou o id. Uma conta que ainda não indexamos não gera 404 nos endpoints de contas; leia catalog.state.
422
invalid_request
A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.Leia error.details: ele indica cada parâmetro inválido e o intervalo esperado.
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.Aguarde os segundos indicados em Retry-After. rate_limited se resolve dentro do minuto; quota_exceeded, às 00:00 UTC.
500
internal_error
Something failed on our side. Internals are never leaked; quote the request id.Tente mais uma vez e, depois, fale com o suporte informando o 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.Tente de novo com backoff em upstream_timeout e upstream_error; uma consulta mais restrita ajuda. not_configured nunca se resolve.

Endpoints

Agrupados do mesmo jeito que a API os agrupa. Abra uma linha para ver os parâmetros, uma requisição pronta para copiar e a resposta que ela retorna.

Cada endpoint tem a sua própria páginaO índice completo, agrupado e com links: método, caminho e o que cada chamada responde, com uma página por endpoint trazendo os parâmetros, um corpo de resposta real e os códigos de erro.
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

Comece no plano grátis

Cem requisições, uma chave, sem cartão. O suficiente para confirmar que os dados são os que você precisa antes de gastar qualquer dinheiro.