Veri API

API referansı

Her uç nokta, döndürdüğü yanıtın aynısıyla. Tek anahtar, tek temel adres, tek zarf ve her satırda gerçek bir örnek gövde.

Anahtar al OpenAPI şeması

Temel adres: https://pinlyx.com/data-api/v2
Sürüm: 2.0.0
Uç nokta: 127
Platform: 7

Bir çağrı nasıl işler

İlk istekten önce bilinecek dört şey. Aşağıdaki her şey bunlardan birinin ayrıntısıdır.

01
Anahtar alın
Panelde bir dakikada, kart olmadan üretilir. Anahtar, paketinizin izin verdiği yetkileri ve bir hız kademesini taşır; sunucudan sunucuya bir kimlik bilgisidir.
02
Katalog mu, canlı mı seçin
Uç noktaların çoğu kendi kataloğumuzu okur: hızlı, önbellekli, tek bütçe birimi. Canlı uç noktalar o an platforma gider, daha pahalıdır ve bunu Canlı rozetiyle söyler.
03
Zarfı okuyun
Başarı her zaman data ve meta demektir. Hata her zaman kararlı bir kod taşıyan error nesnesidir. Biçim uç noktadan uç noktaya değişmez.
04
Başlıkları izleyin
Her yanıt nerede durduğunuzu söyler: kademenizden gelen anlık ve günlük sınırlar, satın aldığınız paketten gelen bütçe. Hiçbir şey sessizce bitmez.

Kimlik doğrulama

Her istek bir anahtar ister. Bearer belirteci olarak gönderin ya da istemciniz için daha uygunsa x-api-key başlığıyla. Anahtarlar panelde üretilir ve sunucudan sunucuya kimlik bilgileridir: anahtarı taşıyan bir sayfada geliştirici araçlarını açan herkes bütün kotanızı eline geçirir.

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

Anahtar biçimi. 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.

Bir yanıtın anatomisi

GET /accounts/{platform}/{handle} çağrısının gerçek yanıtı, API’nin döndürdüğü haliyle. data yanıtın kendisidir. meta ise makbuzu: kimin sunduğu, ne kadar sürdüğü ve sayının kaç yaşında olduğu.

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

data bloğu

Uç noktaya göre biçimlenir ve aşağıda her satırda belgelenmiştir. Hesap uç noktalarında her sayaç bir sayı ya da null’dur; null ölçülmedi demektir, asla sıfır değil.

meta bloğu

request_idstringzorunlu
Unique id for this request. Quote it in a support ticket.
generated_atstringzorunlu
Server time the response was produced.
took_msintegerzorunlu
Milliseconds spent server-side.
pagePageisteğe bağlı
sourcestringisteğe bağlı
Which backend served the payload, for endpoints with more than one.
cache_age_sintegeristeğe bağlı
Age of the underlying data in seconds. 0 for live reads.

Hata zarfı

Hata hiçbir zaman data taşımaz. Kararlı ve sayılı olan error.code değerine göre dallanın; message düz metindir ve değişebilir. details yalnızca invalid_request’te görünür ve sorunlu alanları adlandırır.

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 mu, canlı mı

Çağrı başına verdiğiniz tek karar: tarayıcılarımızın zaten elinde olanı okumak ya da platforma şu saniye sormak.

Katalog okumaları

Kendi veritabanımızdan sunulur: tek indeks sorgusu, milisaniyeler.
Tek bütçe birimine mal olur ve yalnızca kademenizin anlık ve günlük sınırlarından düşer.
meta.cache_age_s okumanın kaç yaşında olduğunu söyler; tazelik tahmin değil, koddaki bir kontroldür.
127 uç noktanın 45 tanesi.

Canlı okumalar

İstek anında platforma gider ve cache_age_s = 0 döner.
Ayrı bir dakikalık canlı kovasından ölçülür ve birden fazla bütçe birimine mal olur; çarpan her pakette yazılıdır.
15 tanesi ayrıca çağrı başına kaynak kredisi harcar ve Kredi harcar rozeti taşır.
Toplam 45 uç nokta; aşağıda her biri satırında Canlı rozeti taşır.

Sayfalama

Liste uç noktaları ?limit= (en çok 500) ve ?cursor= alır. meta.page.next_cursor null olana kadar izleyin; kısa bir sayfa bitiş değildir. İmleçler opak ve imzalıdır: satırlar eklenirken bile sayfalama tutarlı kalır ve elle yazılmış bir imleç reddedilir.

GET /directory/x?limit=50

{
  "data": [
    "..."
  ],
  "meta": {
    "request_id": "req_9f2c41a8b3d5",
    "page": {
      "limit": 50,
      "next_cursor": "eyJrIjoiMTczNDU2IiwiZCI6ImEifQ",
      "count": 50
    }
  }
}

meta.page

limitintegerzorunlu
Rows requested. Default 50, maximum 500.
next_cursorstringzorunlu
Pass as ?cursor= to fetch the next page. null means the result set is exhausted, and it is the only reliable stop condition.
countintegerzorunlu
Rows in this page.
totalintegeristeğe bağlı
Total matching rows. Present only when counting is cheap; never assume it is there.

Yetki alanları

Bir anahtar bir yetki kümesi taşır ve her uç nokta tam olarak bir tanesini ister. Tavanı paket belirler: paketinizde olmayan bir yetki, ilk çağrıda değil anahtar oluşturulurken reddedilir.

directory:read

Read the account and channel catalog across all seven platforms.

scrape:liveHassas

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

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

tools:useHassas

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

Hassas yetkiler yeni bir anahtarda varsayılan olarak yoktur ve altındaki her çağrı denetim kaydına girer.

Hız sınırları ve paket bütçesi

Aynı anda iki kova işler: dakikalık anlık istek tavanı ve günlük kota; ikisi de paketinizin verdiği kademeden gelir. Platforma canlı giden uç noktalar ayrıca sınırlanır, böylece kataloğu hızlı taramak çekicileri aç bırakmaz.

Kademe	Dakikada	Günde	Dakikada canlı
free	30	1,000	5
standard	120	25,000	20
pro	600	250,000	60
unlimited	6,000	10,000,000	600

Kademe tavanları mühendislik sınırlarıdır. Satın aldığınız şey ayrıdır ve kendi başlık ailesinde, X-Plan-* ile bildirilir; aboneliğe bağlı olmayan bir anahtarda bu başlıklar hiç bulunmaz. 429 quota_exceeded zamanla açılır; 402 payment_required açılmaz, kota aşımını fonladığınızda ya da dönemi yenilediğinizde açılır.

Sınır başlıkları

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.

Paket başlıkları

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.

Hata kodları

Sekiz HTTP durumu, on dört kod ve kümenin tamamı bu. Koda göre dallanın: ne yapılacağını bilmek için durum tek başına yetmez.

Durum	Kodlar	Ne zaman	Ne yapmalı
401	`unauthorizedinvalid_key`	No key was presented, or the key is unknown, revoked or expired.	Anahtarı ve başlık adını kontrol edin. İptal edilmiş ya da süresi dolmuş anahtar için panelden yenisini alın.
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.	Panelden kota aşımını fonlayın ya da dönemi yenileyin. Tekrar denemek işe yaramaz.
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.	Yetkiyi anahtarı oluştururken isteyin ya da çağıran adresi anahtarın izin listesine ekleyin.
404	`not_found`	The addressed resource does not exist.	Kullanıcı adını ya da kimliği kontrol edin. Hesap uç noktalarında indekslemediğimiz bir hesap 404 değildir; catalog.state alanını okuyun.
422	`invalid_request`	A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.	error.details alanını okuyun: her hatalı parametreyi ve olması gereken aralığı adlandırır.
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.	Retry-After saniye bekleyin. rate_limited dakika içinde, quota_exceeded 00:00 UTC’de açılır.
500	`internal_error`	Something failed on our side. Internals are never leaked; quote the request id.	Bir kez tekrar deneyin, sonra request_id ile destekle iletişime geçin.
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.	upstream_timeout ve upstream_error için geri çekilerek tekrar deneyin; sorguyu daraltmak yardımcı olur. not_configured hiç açılmaz.

Uç noktalar

API’nin kendi gruplamasıyla. Parametrelerini, kopyalamaya hazır isteği ve döndürdüğü yanıtı görmek için satırı açın.

Her uç noktanın kendi sayfası varGruplanmış, bağlantı verilebilir tam dizin: her çağrının yöntemi, yolu ve neyi yanıtladığı; her uç nokta için parametreleri, gerçek yanıt gövdesi ve hata kodlarıyla ayrı bir sayfa. Sayfalar İngilizcedir.

127 uç noktanın 127 tanesi

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.

Sayfası

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.

Sayfası

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.

Sayfası

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.

Sayfası

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.

Sayfası

Insights32

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

Sayfası

Trends2

Discovery rather than lookup: who gained or lost the most audience on a given day, ranked from the same daily series the growth history is built on. The catalog answers questions about a handle you already have; this answers the question you ask before you have one.

Sayfası

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.

Sayfası

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.

Sayfası

Watch10

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

Sayfası

Research4

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

Sayfası

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.

Sayfası

Leads6

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

Sayfası

pinlyx.com/data-api

Ücretsiz paketle başlayın

Yüz istek, tek anahtar, kart yok. Para hareket etmeden önce verinin ihtiyacınız olan veri olduğunu görmenize yeter.

Anahtar al Neyi yanıtladığına bakın

Bir çağrı nasıl işler

Anahtar alın

Katalog mu, canlı mı seçin

Zarfı okuyun

Başlıkları izleyin

Kimlik doğrulama

Bir yanıtın anatomisi

data bloğu

meta bloğu

Hata zarfı

Katalog mu, canlı mı

Katalog okumaları

Canlı okumalar

Sayfalama

meta.page

Yetki alanları

Hız sınırları ve paket bütçesi

Hata kodları

Uç noktalar

Accounts5

Directory9

X25

People2

Live scrape5

Insights32

Trends2

Identity5

Graph4

Watch10

Research4

Tools18

Leads6

Ücretsiz paketle başlayın