Data API
Справочник API
Все эндпоинты с точным ответом, который они возвращают. Один ключ, один базовый URL, одна обёртка ответа и реальный пример тела в каждой строке.
- Базовый URL
- https://pinlyx.com/data-api/v2
- Версия
- 2.0.0
- Эндпоинты
- 127
- Платформы
- 7
Как устроен вызов
Четыре вещи, которые нужно знать до первого запроса. Всё, что ниже, раскрывает одну из них подробнее.
- 01
Получите ключ
Создаётся в панели за минуту, без карты. Ключ несёт области доступа, разрешённые вашим тарифом, и уровень лимитов, и предназначен для обмена между серверами.
- 02
Выберите каталог или живой запрос
Большинство эндпоинтов читают наш собственный каталог: быстро, из кэша, одна единица бюджета. Живые эндпоинты обращаются к платформе прямо сейчас, стоят дороже и отмечены значком «Живой».
- 03
Разберите обёртку ответа
Успех всегда приходит как data плюс meta. Ошибка всегда приходит как объект error со стабильным кодом. Структура одинакова у всех эндпоинтов.
- 04
Следите за заголовками
Каждый ответ показывает, где вы находитесь: пиковый и дневной лимиты вашего уровня и бюджет купленного тарифа. Ничего не заканчивается молча.
Аутентификация
Каждому запросу нужен ключ. Передавайте его как bearer-токен или в заголовке x-api-key, если вашему клиенту так удобнее. Ключи создаются в панели и предназначены для обмена между серверами: любой, кто откроет devtools на странице с ключом, получит всю вашу квоту.
# 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.
Устройство ответа
Реальный ответ GET /accounts/{platform}/{handle} ровно в том виде, в каком его возвращает API. data — это ответ. meta — это квитанция: кто его выдал, сколько это заняло и насколько свежа цифра.
{
"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
Структура зависит от эндпоинта и описана в каждой строке ниже. В эндпоинтах аккаунтов каждый счётчик — это число или null, а null означает «не измерено», но никогда не ноль.
Блок meta
request_idstringобязательныйUnique id for this request. Quote it in a support ticket.
generated_atstringобязательныйServer time the response was produced.
took_msintegerобязательныйMilliseconds spent server-side.
pagePageнеобязательныйsourcestringнеобязательныйWhich backend served the payload, for endpoints with more than one.
cache_age_sintegerнеобязательныйAge of the underlying data in seconds. 0 for live reads.
Обёртка ошибки
В ответе с ошибкой никогда нет data. Ветвите логику по error.code: он стабилен и перечислен в списке; message — это текст, и он может меняться. details появляется при invalid_request и называет проблемные поля.
{
"error": {
"code": "invalid_request",
"message": "One or more parameters are invalid.",
"details": {
"limit": "Must be between 1 and 500."
},
"request_id": "req_9f2c41a8b3d5"
}
}
Каталог или живой запрос
Единственное решение, которое вы принимаете для каждого вызова: прочитать то, что уже собрали наши краулеры, или спросить платформу прямо сейчас.
Чтение из каталога
- Отдаётся из нашей базы данных: одно обращение к индексу, миллисекунды.
- Стоит одну единицу бюджета и учитывается только в пиковом и дневном лимитах вашего уровня.
- meta.cache_age_s показывает возраст данных, так что свежесть проверяется в коде, а не на глаз.
- Эндпоинтов: 45 из 127.
Живое чтение
- Обращается к платформе в момент запроса и возвращает cache_age_s = 0.
- Учитывается в отдельном поминутном лимите живых запросов и стоит больше одной единицы бюджета; множитель указан в каждом тарифе.
- Из них 15 также тратят кредиты внешнего источника за каждый вызов и отмечены значком «Тратит кредиты».
- Всего таких эндпоинтов: 45, у каждого в строке ниже есть значок «Живой».
Пагинация
Эндпоинты списков принимают ?limit= (до 500) и ?cursor=. Переходите по meta.page.next_cursor, пока он не станет null; короткая страница ещё не означает конец. Курсоры непрозрачные и подписанные, поэтому постраничное чтение остаётся согласованным, пока добавляются строки, а курсор, написанный вручную, отклоняется.
{
"data": [
"..."
],
"meta": {
"request_id": "req_9f2c41a8b3d5",
"page": {
"limit": 50,
"next_cursor": "eyJrIjoiMTczNDU2IiwiZCI6ImEifQ",
"count": 50
}
}
}
meta.page
limitintegerобязательныйRows requested. Default 50, maximum 500.
next_cursorstringобязательныйPass as ?cursor= to fetch the next page. null means the result set is exhausted, and it is the only reliable stop condition.
countintegerобязательныйRows in this page.
totalintegerнеобязательныйTotal matching rows. Present only when counting is cheap; never assume it is there.
Области доступа
Ключ несёт набор областей доступа, а каждый эндпоинт требует ровно одну. Тариф задаёт потолок: запрос области, которой нет в вашем тарифе, отклоняется при создании ключа, а не при первом вызове.
directory:readRead the account and channel catalog across all seven platforms.
scrape:liveЧувствительная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:readEngagement rates, top posts, viral patterns, cohort benchmarks.
research:readFindings, runs and events from the autonomous research engine.
leads:readЧувствительнаяLinkedIn company and contact data, and X follower-graph exports.
tools:useЧувствительнаяRun the analysis tools: valuation, follower audit, scoring, and more.
Чувствительные области по умолчанию не добавляются к новому ключу, а каждый вызов в них записывается в журнал аудита.
Лимиты частоты и бюджет тарифа
Одновременно действуют два ограничения: пиковый потолок в минуту и квота в день, оба по уровню, который даёт ваш тариф. Эндпоинты, обращающиеся к платформе вживую, ограничены отдельно, так что быстрое постраничное чтение каталога никогда не отнимает ресурс у живых запросов.
| Уровень | В минуту | В день | Живых в минуту |
|---|---|---|---|
| free | 30 | 1 000 | 5 |
| standard | 120 | 25 000 | 20 |
| pro | 600 | 250 000 | 60 |
| unlimited | 6 000 | 10 000 000 | 600 |
Потолки уровней — это технические ограничения. Купленный объём учитывается отдельно и передаётся в собственном семействе заголовков X-Plan-*, которых вообще нет у ключа, не привязанного к подписке. 429 quota_exceeded снимается со временем; 402 payment_required сам не снимается, он исчезает, когда вы оплатите перерасход или продлите период.
Заголовки лимитов
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.
Заголовки тарифа
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.
Коды ошибок
Восемь HTTP-статусов, четырнадцать кодов, и это полный список. Ветвите логику по коду: одного статуса недостаточно, чтобы понять, что делать.
| Статус | Коды | Когда | Что делать |
|---|---|---|---|
| 401 | unauthorizedinvalid_key | No key was presented, or the key is unknown, revoked or expired. | Проверьте ключ и название заголовка. Для отозванного или просроченного ключа нужен новый из панели. |
| 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. | Оплатите перерасход или продлите период в панели. Повторные попытки не помогут. |
| 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. | Запросите область доступа при создании ключа или добавьте адрес вызывающей стороны в список разрешённых для ключа. |
| 404 | not_found | The addressed resource does not exist. | Проверьте хэндл или id. Аккаунт, который мы ещё не проиндексировали, в эндпоинтах аккаунтов не даёт 404; смотрите catalog.state. |
| 422 | invalid_request | A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields. | Прочитайте error.details: там названы все неверные параметры и допустимые диапазоны. |
| 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 секунд. rate_limited снимается в течение минуты, quota_exceeded в 00:00 UTC. |
| 500 | internal_error | Something failed on our side. Internals are never leaked; quote the request id. | Повторите один раз, затем напишите в поддержку, указав 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. | При upstream_timeout и upstream_error повторяйте с нарастающей паузой; помогает более узкий запрос. not_configured не снимается никогда. |
Эндпоинты
Сгруппированы так же, как в самом API. Откройте строку, чтобы увидеть параметры, готовый к копированию запрос и ответ, который он возвращает.
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.
Начните с бесплатного тарифа
Сто запросов, один ключ, без карты. Достаточно, чтобы убедиться, что данные именно те, что вам нужны, прежде чем платить.