Data API

Справочник API

Все эндпоинты с точным ответом, который они возвращают. Один ключ, один базовый URL, одна обёртка ответа и реальный пример тела в каждой строке.

Базовый URL
https://pinlyx.com/data-api/v2
Версия
2.0.0
Эндпоинты
127
Платформы
7

Как устроен вызов

Четыре вещи, которые нужно знать до первого запроса. Всё, что ниже, раскрывает одну из них подробнее.

  1. 01

    Получите ключ

    Создаётся в панели за минуту, без карты. Ключ несёт области доступа, разрешённые вашим тарифом, и уровень лимитов, и предназначен для обмена между серверами.

  2. 02

    Выберите каталог или живой запрос

    Большинство эндпоинтов читают наш собственный каталог: быстро, из кэша, одна единица бюджета. Живые эндпоинты обращаются к платформе прямо сейчас, стоят дороже и отмечены значком «Живой».

  3. 03

    Разберите обёртку ответа

    Успех всегда приходит как data плюс meta. Ошибка всегда приходит как объект error со стабильным кодом. Структура одинакова у всех эндпоинтов.

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

Устройство ответа

Реальный ответ GET /accounts/{platform}/{handle} ровно в том виде, в каком его возвращает API. data — это ответ. meta — это квитанция: кто его выдал, сколько это заняло и насколько свежа цифра.

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

Структура зависит от эндпоинта и описана в каждой строке ниже. В эндпоинтах аккаунтов каждый счётчик — это число или 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 и называет проблемные поля.

422
{
  "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; короткая страница ещё не означает конец. Курсоры непрозрачные и подписанные, поэтому постраничное чтение остаётся согласованным, пока добавляются строки, а курсор, написанный вручную, отклоняется.

GET /directory/x?limit=50
{
  "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:read

    Read 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:read

    Engagement rates, top posts, viral patterns, cohort benchmarks.

  • research:read

    Findings, 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.

Чувствительные области по умолчанию не добавляются к новому ключу, а каждый вызов в них записывается в журнал аудита.

Лимиты частоты и бюджет тарифа

Одновременно действуют два ограничения: пиковый потолок в минуту и квота в день, оба по уровню, который даёт ваш тариф. Эндпоинты, обращающиеся к платформе вживую, ограничены отдельно, так что быстрое постраничное чтение каталога никогда не отнимает ресурс у живых запросов.

УровеньВ минутуВ деньЖивых в минуту
free301 0005
standard12025 00020
pro600250 00060
unlimited6 00010 000 000600

Потолки уровней — это технические ограничения. Купленный объём учитывается отдельно и передаётся в собственном семействе заголовков X-Plan-*, которых вообще нет у ключа, не привязанного к подписке. 429 quota_exceeded снимается со временем; 402 payment_required сам не снимается, он исчезает, когда вы оплатите перерасход или продлите период.

Заголовки лимитов

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

Заголовки тарифа

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

Коды ошибок

Восемь 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. Откройте строку, чтобы увидеть параметры, готовый к копированию запрос и ответ, который он возвращает.

У каждого эндпоинта своя страницаПолный указатель с группами и ссылками: метод, путь и на что отвечает каждый вызов, а на странице каждого эндпоинта есть параметры, реальное тело ответа и коды ошибок.
Показано эндпоинтов: 127 из 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.

Полная страница
Полная страница
Полная страница
Полная страница
Полная страница

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.

Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница

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.

Полная страница
Полная страница
Полная страница
Полная страница
Полная страница
Полная страница

pinlyx.com/data-api

Начните с бесплатного тарифа

Сто запросов, один ключ, без карты. Достаточно, чтобы убедиться, что данные именно те, что вам нужны, прежде чем платить.