Data API
Referensi API
Setiap endpoint dengan respons persis yang dikembalikannya. Satu kunci, satu base URL, satu format respons, dan contoh body nyata di setiap baris.
- Base URL
- https://pinlyx.com/data-api/v2
- Versi
- 2.0.0
- Endpoint
- 127
- Platform
- 7
Cara kerja sebuah panggilan
Empat hal yang perlu diketahui sebelum permintaan pertama. Semua yang ada di bawah adalah rincian dari salah satunya.
- 01
Dapatkan kunci
Dibuat di panel dalam satu menit, tanpa kartu. Kunci membawa scope yang diizinkan paket Anda dan satu tingkat batas (tier), dan merupakan kredensial antar-server.
- 02
Pilih katalog atau langsung
Sebagian besar endpoint membaca katalog kami sendiri: cepat, ter-cache, satu unit anggaran. Endpoint langsung menghubungi platform saat itu juga, lebih mahal, dan ditandai dengan lencana Live.
- 03
Baca format responsnya
Respons sukses selalu berisi data dan meta. Respons gagal selalu berupa objek error dengan kode yang stabil. Bentuknya tidak pernah berubah antar-endpoint.
- 04
Perhatikan header-nya
Setiap respons memberi tahu posisi Anda: batas burst dan harian dari tier Anda, kuota paket dari apa yang Anda beli. Tidak ada yang habis diam-diam.
Autentikasi
Setiap permintaan membutuhkan kunci. Kirim sebagai bearer token, atau sebagai x-api-key jika itu lebih cocok untuk klien Anda. Kunci dibuat di panel dan merupakan kredensial antar-server: siapa pun yang membuka devtools di halaman yang memuat kunci akan mendapatkan seluruh kuota Anda.
# 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_..."
psk_live_... for production keys, psk_test_... for test keysKeys are server-to-server credentials. Never embed one in front-end code - call the API from your own backend and forward the result.
Anatomi sebuah respons
Jawaban nyata dari GET /accounts/{platform}/{handle}, persis seperti yang dikembalikan API. data adalah jawabannya. meta adalah tanda terimanya: siapa yang melayani, berapa lama prosesnya, dan seberapa lama angka itu dibaca.
{
"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
}
}
Blok data
Bentuknya berbeda per endpoint dan didokumentasikan di setiap baris di bawah. Di endpoint akun, setiap hitungan berupa angka atau null, dan null berarti tidak diukur, bukan nol.
Blok meta
request_idstringwajibUnique id for this request. Quote it in a support ticket.
generated_atstringwajibServer time the response was produced.
took_msintegerwajibMilliseconds spent server-side.
pagePageopsionalsourcestringopsionalWhich backend served the payload, for endpoints with more than one.
cache_age_sintegeropsionalAge of the underlying data in seconds. 0 for live reads.
Format respons error
Respons gagal tidak pernah membawa data. Buat percabangan berdasarkan error.code, yang stabil dan terdaftar; message berupa teks bebas dan bisa berubah. details muncul pada invalid_request dan menyebutkan field yang bermasalah.
{
"error": {
"code": "invalid_request",
"message": "One or more parameters are invalid.",
"details": {
"limit": "Must be between 1 and 500."
},
"request_id": "req_9f2c41a8b3d5"
}
}
Katalog atau langsung
Satu-satunya keputusan yang Anda ambil di setiap panggilan: baca apa yang sudah dikumpulkan crawler kami, atau tanyakan ke platform detik ini juga.
Pembacaan katalog
- Dilayani dari database kami sendiri: satu kali pencarian indeks, hitungan milidetik.
- Memakai satu unit anggaran dan hanya dihitung terhadap batas burst dan harian tier Anda.
- meta.cache_age_s memberi tahu seberapa lama data itu dibaca, jadi kesegaran data dicek lewat kode, bukan ditebak.
- 45 dari 127 endpoint.
Pembacaan langsung
- Menghubungi platform saat permintaan dibuat dan mengembalikan cache_age_s = 0.
- Dihitung terhadap kuota live-per-menit yang terpisah dan memakai lebih dari satu unit anggaran; pengalinya tercantum di setiap paket.
- 15 di antaranya juga memakai kredit upstream per panggilan, dan diberi lencana Memakai kredit.
- Total 45 endpoint, masing-masing dengan lencana Live di barisnya di bawah.
Paginasi
Endpoint daftar menerima ?limit= (hingga 500) dan ?cursor=. Ikuti meta.page.next_cursor sampai nilainya null; halaman yang pendek bukan berarti akhir. Cursor bersifat opaque dan ditandatangani, jadi paginasi tetap konsisten selama baris baru ditambahkan, dan cursor yang ditulis manual akan ditolak.
{
"data": [
"..."
],
"meta": {
"request_id": "req_9f2c41a8b3d5",
"page": {
"limit": 50,
"next_cursor": "eyJrIjoiMTczNDU2IiwiZCI6ImEifQ",
"count": 50
}
}
}
meta.page
limitintegerwajibRows requested. Default 50, maximum 500.
next_cursorstringwajibPass as ?cursor= to fetch the next page. null means the result set is exhausted, and it is the only reliable stop condition.
countintegerwajibRows in this page.
totalintegeropsionalTotal matching rows. Present only when counting is cheap; never assume it is there.
Scope
Sebuah kunci membawa sekumpulan scope dan setiap endpoint menyatakan tepat satu scope. Paket adalah batas atasnya: meminta scope yang tidak termasuk dalam paket Anda akan ditolak saat kunci dibuat, bukan saat panggilan pertama.
directory:readRead the account and channel catalog across all seven platforms.
scrape:liveSensitifRead 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:readEngagement rates, top posts, viral patterns, cohort benchmarks.
research:readFindings, runs and events from the autonomous research engine.
leads:readSensitifLinkedIn company and contact data, and X follower-graph exports.
tools:useSensitifRun the analysis tools: valuation, follower audit, scoring, and more.
Scope sensitif tidak otomatis ada di kunci baru, dan setiap panggilan di bawahnya diaudit.
Rate limit dan kuota paket
Dua batas berlaku sekaligus: batas burst per menit dan kuota per hari, keduanya dari tier yang diberikan paket Anda. Endpoint yang menghubungi platform secara langsung dibatasi terpisah, jadi membaca katalog dengan cepat tidak pernah menghabiskan jatah pengambilan langsung.
| Tier | Per menit | Per hari | Live per menit |
|---|---|---|---|
| free | 30 | 1.000 | 5 |
| standard | 120 | 25.000 | 20 |
| pro | 600 | 250.000 | 60 |
| unlimited | 6.000 | 10.000.000 | 600 |
Batas tier adalah batas teknis. Apa yang Anda beli terpisah dan dilaporkan dalam kelompok header-nya sendiri, X-Plan-*, yang sama sekali tidak muncul pada kunci yang tidak terhubung ke langganan. 429 quota_exceeded pulih sesuai jam; 402 payment_required tidak, ia baru pulih saat Anda mendanai overage atau memperpanjang periode.
Header batas
X-RateLimit-LimitRequests allowed in the current one-minute window.
X-RateLimit-RemainingRequests left in the current one-minute window.
X-RateLimit-ResetUnix seconds at which the current window resets.
X-Quota-LimitRequests allowed today, from your tier.
X-Quota-RemainingRequests left in today's quota.
Retry-AfterSeconds to wait before retrying.
X-Request-IdUnique id for this request, echoed in meta.request_id.
Header paket
X-PlanPlan id behind the key.
X-Plan-LimitRequests included in the current billing period.
X-Plan-RemainingIncluded requests left in the current billing period.
X-Plan-OverageRequests served beyond the included allowance so far this period.
X-Plan-Period-EndWhen the current billing period ends, ISO 8601.
Kode error
Delapan status HTTP, empat belas kode, dan hanya itu set lengkapnya. Buat percabangan berdasarkan kode: status saja tidak cukup untuk tahu apa yang harus dilakukan.
| Status | Kode | Kapan | Yang harus dilakukan |
|---|---|---|---|
| 401 | unauthorizedinvalid_key | No key was presented, or the key is unknown, revoked or expired. | Periksa kunci dan nama header-nya. Kunci yang dicabut atau kedaluwarsa perlu diganti dengan kunci baru dari 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. | Danai overage atau perpanjang periode di panel. Mencoba ulang tidak akan membantu. |
| 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. | Minta scope tersebut saat membuat kunci, atau tambahkan alamat pemanggil ke allowlist kunci. |
| 404 | not_found | The addressed resource does not exist. | Periksa handle atau id. Akun yang belum kami indeks tidak menghasilkan 404 di endpoint akun; baca catalog.state sebagai gantinya. |
| 422 | invalid_request | A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields. | Baca error.details: isinya menyebutkan setiap parameter yang salah dan rentang nilai yang seharusnya. |
| 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. | Tunggu selama Retry-After detik. rate_limited pulih dalam satu menit; quota_exceeded pada pukul 00:00 UTC. |
| 500 | internal_error | Something failed on our side. Internals are never leaked; quote the request id. | Coba ulang sekali, lalu hubungi dukungan dengan menyertakan 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. | Coba ulang dengan backoff pada upstream_timeout dan upstream_error; kueri yang lebih sempit membantu. not_configured tidak pernah pulih. |
Endpoint
Dikelompokkan seperti pengelompokan di API. Buka sebuah baris untuk melihat parameternya, permintaan yang siap disalin, dan respons yang dikembalikannya.
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.
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.
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.
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.
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.
Insights32
Derived engagement intelligence: engagement rates, top and viral posts, posting patterns and cohort benchmarks computed over the post layer.
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.
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.
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.
Watch10
Webhooks. Register a destination, prove you control it, watch accounts for audience change, and read or replay every delivery.
Research4
Findings, runs and events from the autonomous research engine, which decides on its own which pools to expand and reports what it learned.
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.
Leads6
B2B lead data: LinkedIn companies and decision makers, plus X follower-graph exports. Sensitive by nature, separately scoped, and never granted by default.
Mulai dengan paket Free
Seratus permintaan, satu kunci, tanpa kartu. Cukup untuk memastikan datanya memang data yang Anda butuhkan sebelum ada uang yang keluar.