Data API

API-Referenz

Jeder Endpunkt mit genau der Antwort, die er liefert. Ein Schlüssel, eine Basis-URL, ein Envelope und in jeder Zeile ein echter Beispiel-Body.

Basis-URL
https://pinlyx.com/data-api/v2
Version
2.0.0
Endpunkte
127
Plattformen
7

So funktioniert ein Aufruf

Vier Dinge sollten Sie vor der ersten Anfrage wissen. Alles weiter unten vertieft einen dieser Punkte.

  1. 01

    Schlüssel holen

    In einer Minute im Panel erstellt, ohne Kreditkarte. Ein Schlüssel trägt die Scopes, die Ihr Plan erlaubt, und eine Rate-Stufe, und er ist ein Zugangsnachweis für Server-zu-Server-Aufrufe.

  2. 02

    Katalog oder live wählen

    Die meisten Endpunkte lesen unseren eigenen Katalog: schnell, gecacht, eine Budgeteinheit. Live-Endpunkte fragen die Plattform in diesem Moment ab, kosten mehr und sind mit einem Live-Badge gekennzeichnet.

  3. 03

    Den Envelope lesen

    Erfolg bedeutet immer data plus meta. Ein Fehler ist immer ein error-Objekt mit stabilem Code. Die Struktur ist bei allen Endpunkten gleich.

  4. 04

    Die Header im Blick behalten

    Jede Antwort zeigt Ihnen, wo Sie stehen: Burst- und Tageslimits aus Ihrer Stufe, Planbudget aus dem, was Sie gekauft haben. Nichts geht unbemerkt zur Neige.

Authentifizierung

Jede Anfrage braucht einen Schlüssel. Senden Sie ihn als Bearer-Token oder als x-api-key, falls das besser zu Ihrem Client passt. Schlüssel werden im Panel erstellt und sind Zugangsnachweise für Server-zu-Server-Aufrufe: Wer auf einer Seite, die einen Schlüssel enthält, die Devtools öffnet, hat Ihr gesamtes Kontingent.

# 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_..."
Schlüsselformat. 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.

Aufbau einer Antwort

Eine echte Antwort von GET /accounts/{platform}/{handle}, genau so, wie die API sie liefert. data ist die Antwort. meta ist der Beleg: wer sie ausgeliefert hat, wie lange es gedauert hat und wie alt die Zahl ist.

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

Der data-Block

Je nach Endpunkt aufgebaut und in jeder Zeile unten dokumentiert. Bei den Account-Endpunkten ist jeder Zählwert eine Zahl oder null, und null bedeutet „nicht gemessen“, niemals null Stück.

Der meta-Block

  • request_idstringPflicht

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

  • generated_atstringPflicht

    Server time the response was produced.

  • took_msintegerPflicht

    Milliseconds spent server-side.

  • pagePageoptional
  • sourcestringoptional

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

  • cache_age_sintegeroptional

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

Der Fehler-Envelope

Ein Fehler enthält nie data. Verzweigen Sie anhand von error.code, der stabil und abschließend aufgezählt ist; message ist Fließtext und kann sich ändern. details erscheint bei invalid_request und nennt die fehlerhaften Felder.

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

Katalog oder live

Die eine Entscheidung pro Aufruf: lesen, was unsere Crawler bereits haben, oder die Plattform in dieser Sekunde fragen.

Katalogabfragen

  • Aus unserer eigenen Datenbank ausgeliefert: ein Indexzugriff, Millisekunden.
  • Kostet eine Budgeteinheit und zählt nur gegen die Burst- und Tageslimits Ihrer Stufe.
  • meta.cache_age_s gibt das Alter des Messwerts an, Aktualität ist also eine Prüfung im Code statt einer Vermutung.
  • 45 von 127 Endpunkten.

Live-Abfragen

  • Fragen die Plattform zum Zeitpunkt der Anfrage ab und liefern cache_age_s = 0.
  • Werden über ein separates Live-Kontingent pro Minute abgerechnet und kosten mehr als eine Budgeteinheit; der Multiplikator steht bei jedem Plan.
  • 15 davon verbrauchen zusätzlich pro Aufruf Upstream-Credits und tragen ein Badge „Verbraucht Credits“.
  • Insgesamt 45 Endpunkte, jeder mit einem Live-Badge in seiner Zeile unten.

Paginierung

Listen-Endpunkte akzeptieren ?limit= (bis 500) und ?cursor=. Folgen Sie meta.page.next_cursor, bis der Wert null ist; eine kurze Seite ist nicht das Ende. Cursor sind undurchsichtig und signiert, sodass das Blättern konsistent bleibt, während Zeilen eingefügt werden, und ein selbst geschriebener Cursor wird abgelehnt.

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

meta.page

  • limitintegerPflicht

    Rows requested. Default 50, maximum 500.

  • next_cursorstringPflicht

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

  • countintegerPflicht

    Rows in this page.

  • totalintegeroptional

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

Scopes

Ein Schlüssel trägt eine Reihe von Scopes, und jeder Endpunkt deklariert genau einen. Der Plan ist die Obergrenze: Wer einen Scope anfordert, den der Plan nicht enthält, wird schon beim Erstellen des Schlüssels abgewiesen, nicht erst beim ersten Aufruf.

  • directory:read

    Read the account and channel catalog across all seven platforms.

  • scrape:liveSensibel

    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:readSensibel

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

  • tools:useSensibel

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

Sensible Scopes sind auf einem neuen Schlüssel standardmäßig nicht enthalten, und jeder Aufruf damit wird protokolliert.

Rate-Limits und Planbudget

Zwei Kontingente gelten gleichzeitig: eine Burst-Obergrenze pro Minute und eine Quote pro Tag, beide aus der Stufe, die Ihr Plan gewährt. Endpunkte, die live auf eine Plattform zugreifen, sind separat begrenzt, sodass schnelles Blättern im Katalog die Live-Abrufe nie ausbremst.

StufePro MinutePro TagLive pro Minute
free301.0005
standard12025.00020
pro600250.00060
unlimited6.00010.000.000600

Die Obergrenzen der Stufen sind technische Limits. Was Sie gekauft haben, ist davon getrennt und wird in einer eigenen Header-Familie gemeldet, X-Plan-*, die bei einem Schlüssel ohne Abonnement komplett fehlt. 429 quota_exceeded löst sich nach Zeitablauf; 402 payment_required nicht, das löst sich erst, wenn Sie die Mehrnutzung bezahlen oder den Zeitraum verlängern.

Limit-Header

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

Plan-Header

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

Fehlercodes

Acht HTTP-Status, vierzehn Codes, und das ist die vollständige Liste. Verzweigen Sie anhand des Codes: Der Status allein reicht nicht, um zu wissen, was zu tun ist.

StatusCodesWannWas tun
401
unauthorizedinvalid_key
No key was presented, or the key is unknown, revoked or expired.Prüfen Sie den Schlüssel und den Header-Namen. Ein widerrufener oder abgelaufener Schlüssel muss im Panel neu erstellt werden.
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.Bezahlen Sie die Mehrnutzung oder verlängern Sie den Zeitraum im Panel. Erneute Versuche helfen nicht.
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.Fordern Sie den Scope beim Erstellen des Schlüssels an, oder setzen Sie die Adresse des Aufrufers auf die Allowlist des Schlüssels.
404
not_found
The addressed resource does not exist.Prüfen Sie Handle oder ID. Ein Konto, das wir noch nicht indexiert haben, ergibt bei den Account-Endpunkten keinen 404; lesen Sie stattdessen catalog.state.
422
invalid_request
A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.Lesen Sie error.details: Dort steht jeder fehlerhafte Parameter mit dem zulässigen Bereich.
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.Warten Sie Retry-After Sekunden. rate_limited löst sich innerhalb der Minute, quota_exceeded um 00:00 UTC.
500
internal_error
Something failed on our side. Internals are never leaked; quote the request id.Einmal erneut versuchen, dann den Support mit der request_id kontaktieren.
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.Bei upstream_timeout und upstream_error mit Backoff erneut versuchen; eine engere Abfrage hilft. not_configured löst sich nie.

Endpunkte

So gruppiert, wie die API sie gruppiert. Öffnen Sie eine Zeile für Parameter, eine kopierfertige Anfrage und die gelieferte Antwort.

Jeder Endpunkt hat eine eigene SeiteDer vollständige Index, gruppiert und verlinkbar: Methode, Pfad und was jeder Aufruf beantwortet, mit einer Seite pro Endpunkt samt Parametern, echtem Antwort-Body und Fehlercodes.
127 von 127 Endpunkten

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

Insights32

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

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

Watch10

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

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

Research4

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

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

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.

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

Leads6

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

Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite
Ganze Seite

pinlyx.com/data-api

Mit dem Free-Plan starten

Hundert Anfragen, ein Schlüssel, keine Kreditkarte. Genug, um zu prüfen, ob die Daten die sind, die Sie brauchen, bevor Geld fließt.