Data API

Référence de l’API

Chaque endpoint avec la réponse exacte qu’il renvoie. Une clé, une URL de base, une enveloppe, et un vrai exemple de corps de réponse sur chaque ligne.

URL de base
https://pinlyx.com/data-api/v2
Version
2.0.0
Endpoints
127
Plateformes
7

Comment se déroule un appel

Quatre choses à savoir avant la première requête. Tout ce qui suit détaille l’une d’elles.

  1. 01

    Obtenir une clé

    Créée dans le panneau en une minute, sans carte bancaire. Une clé porte les scopes autorisés par votre offre et un palier de débit ; c’est un identifiant de serveur à serveur.

  2. 02

    Choisir catalogue ou direct

    La plupart des endpoints lisent notre propre catalogue : rapide, mis en cache, une unité de budget. Les endpoints en direct interrogent la plateforme sur le moment, coûtent plus cher et l’indiquent par un badge Direct.

  3. 03

    Lire l’enveloppe

    Un succès renvoie toujours data et meta. Un échec renvoie toujours un objet error avec un code stable. La forme ne change jamais d’un endpoint à l’autre.

  4. 04

    Surveiller les en-têtes

    Chaque réponse vous dit où vous en êtes : limites par rafale et par jour selon votre palier, budget de l’offre selon ce que vous avez acheté. Rien ne s’épuise sans prévenir.

Authentification

Chaque requête exige une clé. Envoyez-la comme jeton bearer, ou dans x-api-key si cela convient mieux à votre client. Les clés sont créées dans le panneau et sont des identifiants de serveur à serveur : quiconque ouvre les outils de développement sur une page qui en contient une dispose de tout votre quota.

# 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_..."
Format de la clé. 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.

Anatomie d’une réponse

Une vraie réponse de GET /accounts/{platform}/{handle}, exactement telle que l’API la renvoie. data est la réponse. meta est le reçu : qui l’a servie, en combien de temps et quel âge a le chiffre.

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

Le bloc data

Sa forme dépend de l’endpoint et elle est documentée sur chaque ligne ci-dessous. Sur les endpoints de compte, chaque compteur est un nombre ou null, et null signifie non mesuré, jamais zéro.

Le bloc meta

  • request_idstringobligatoire

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

  • generated_atstringobligatoire

    Server time the response was produced.

  • took_msintegerobligatoire

    Milliseconds spent server-side.

  • pagePagefacultatif
  • sourcestringfacultatif

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

  • cache_age_sintegerfacultatif

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

L’enveloppe d’erreur

Un échec ne contient jamais data. Basez votre logique sur error.code, stable et énuméré ; message est un texte libre et peut changer. details apparaît sur invalid_request et nomme les champs en cause.

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

Catalogue ou direct

La seule décision à prendre à chaque appel : lire ce que nos robots ont déjà collecté, ou interroger la plateforme à la seconde.

Lectures du catalogue

  • Servies depuis notre propre base de données : une seule lecture d’index, quelques millisecondes.
  • Coûtent une unité de budget et ne comptent que dans les limites par rafale et par jour de votre palier.
  • meta.cache_age_s indique l’âge de la mesure : la fraîcheur se vérifie dans le code, sans deviner.
  • Endpoints concernés : 45 sur 127.

Lectures en direct

  • Interrogent la plateforme au moment de la requête et renvoient cache_age_s = 0.
  • Décomptées sur un quota distinct d’appels en direct par minute, elles coûtent plus d’une unité de budget ; le multiplicateur figure dans chaque offre.
  • Parmi eux, 15 consomment aussi des crédits en amont à chaque appel et portent un badge Consomme des crédits.
  • Endpoints concernés au total : 45, chacun avec un badge Direct sur sa ligne ci-dessous.

Pagination

Les endpoints de liste acceptent ?limit= (jusqu’à 500) et ?cursor=. Suivez meta.page.next_cursor jusqu’à ce qu’il vaille null ; une page incomplète ne signifie pas la fin. Les curseurs sont opaques et signés : la pagination reste cohérente pendant l’insertion de lignes, et un curseur écrit à la main est rejeté.

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

meta.page

  • limitintegerobligatoire

    Rows requested. Default 50, maximum 500.

  • next_cursorstringobligatoire

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

  • countintegerobligatoire

    Rows in this page.

  • totalintegerfacultatif

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

Scopes

Une clé porte un ensemble de scopes, et chaque endpoint en déclare exactement un. L’offre fixe le plafond : demander un scope que votre offre n’inclut pas est refusé à la création de la clé, pas au premier appel.

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

Les scopes sensibles ne sont pas attribués par défaut à une nouvelle clé, et chaque appel qui en relève est journalisé.

Limites de débit et budget de l’offre

Deux quotas s’appliquent en même temps : un plafond par rafale à la minute et un quota par jour, tous deux fixés par le palier que vous accorde votre offre. Les endpoints qui interrogent une plateforme en direct sont plafonnés à part, pour que parcourir rapidement le catalogue ne prive jamais les lectures en direct.

PalierPar minutePar jourDirect par minute
free301 0005
standard12025 00020
pro600250 00060
unlimited6 00010 000 000600

Les plafonds de palier sont des limites techniques. Ce que vous avez acheté est distinct et remonte dans sa propre famille d’en-têtes, X-Plan-*, totalement absente sur une clé qui n’est rattachée à aucun abonnement. 429 quota_exceeded se lève avec le temps ; 402 payment_required, non : il se lève quand vous financez le dépassement ou renouvelez la période.

En-têtes 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.

En-têtes de l’offre

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

Codes d’erreur

Huit statuts HTTP, quatorze codes, et c’est la liste complète. Basez-vous sur le code : le statut seul ne suffit pas pour savoir quoi faire.

StatutCodesQuandQue faire
401
unauthorizedinvalid_key
No key was presented, or the key is unknown, revoked or expired.Vérifiez la clé et le nom de l’en-tête. Une clé révoquée ou expirée doit être remplacée depuis le panneau.
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.Financez le dépassement ou renouvelez la période dans le panneau. Réessayer ne sert à rien.
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.Demandez le scope à la création de la clé, ou ajoutez l’adresse de l’appelant à la liste d’autorisation de la clé.
404
not_found
The addressed resource does not exist.Vérifiez l’identifiant. Sur les endpoints de compte, un compte que nous n’avons pas indexé ne renvoie pas 404 ; lisez plutôt catalog.state.
422
invalid_request
A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.Lisez error.details : il nomme chaque paramètre invalide et la plage attendue.
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.Attendez Retry-After secondes. rate_limited se lève dans la minute ; quota_exceeded à 00:00 UTC.
500
internal_error
Something failed on our side. Internals are never leaked; quote the request id.Réessayez une fois, puis contactez le support avec le 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.Réessayez avec un délai croissant sur upstream_timeout et upstream_error ; une requête plus ciblée aide. not_configured ne se lève jamais.

Endpoints

Regroupés comme l’API les regroupe. Ouvrez une ligne pour voir ses paramètres, une requête prête à copier et la réponse renvoyée.

Chaque endpoint a sa propre pageL’index complet, organisé et avec des liens : méthode, chemin et ce que renvoie chaque appel, avec une page par endpoint qui présente ses paramètres, un vrai corps de réponse et ses codes d’erreur.
Endpoints affichés : 127 sur 127

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.

Page complète
Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète
Page complète

Insights32

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

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète

Watch10

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

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

Research4

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

Page complète
Page complète
Page complète
Page complète

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.

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

Leads6

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

Page complète
Page complète
Page complète
Page complète
Page complète
Page complète

pinlyx.com/data-api

Commencez avec l’offre gratuite

Cent requêtes, une clé, aucune carte bancaire. De quoi vérifier que les données correspondent à votre besoin avant de dépenser quoi que ce soit.