İçeriğe geç

Hesap Analizi

GET/v1/tiktok/user/analytics3 kredi

Bir hesabın etkileşimini profilinden ve son videolarından hesaplar: ortalama ve medyan beğeni, yorum ve oynatma sayıları, takipçiye ve oynatmaya göre etkileşim oranları ve paylaşım sıklığı; örneklem büyüklüğü ve zaman aralığıyla birlikte.

01Sorgu parametreleri

AdTürAçıklama
handlezorunlustringTikTok kullanıcı adı (başında `@` olabilir).
postsisteğe bağlıintegerÖrneklenecek son gönderi sayısı, 1 ile 50 arası. Sabitlenmiş videolar dışarıda bırakılır.Varsayılan: 20
tzisteğe bağlıstring`posting_times` içindeki gün ve saatlerin okunacağı IANA saat dilimi, örneğin `Europe/Istanbul` veya `America/New_York`. Yaz saati her gönderinin kendi tarihine göre uygulanır. Başka bir değer ücretsiz 400 döner.Varsayılan: UTC

02Fiyatlandırma

Profil için 1 kredi ve okunan her 10 videoluk sayfa için 1 kredi: varsayılan 20 video için 3 kredi. Bir isteğin en yüksek maliyeti (1 + ⌈posts/10⌉) bakiyenizde bulunmalıdır; erken biten bir liste daha az tutar, başarısız çağrı ücretsizdir.

03İstek

curl "https://api.scrapesocial.ai/v1/tiktok/user/analytics?handle=tiktok&tz=Europe%2FIstanbul" \
  -H "x-api-key: $SCRAPESOCIAL_KEY"

04Yanıtlar

API'nin gerçek yanıtları. Listeler 2 öğeye kısaltılmıştır.

GET /v1/tiktok/user/analytics?handle=tiktok&tz=Europe/Istanbul

{
  "success": true,
  "credits_remaining": 4980,
  "credits_charged": 3,
  "platform": "tiktok",
  "owner": {
    "id": "107955",
    "username": "tiktok",
    "display_name": "TikTok"
  },
  "followers": 96441362,
  "sample": {
    "posts": 20,
    "from": "2026-08-20T15:22:21Z",
    "to": "2026-10-23T23:29:02Z",
    "posts_read": 20,
    "pinned_excluded": 0,
    "reposts_excluded": 0
  },
  "likes": {
    "posts": 20,
    "missing": 0,
    "total": 369571,
    "average": 18478.55,
    "median": 14800
  },
  "comments": {
    "posts": 20,
    "missing": 0,
    "total": 54778,
    "average": 2738.9,
    "median": 2472.5
  },
  "views": {
    "posts": 20,
    "missing": 0,
    "total": 10417000,
    "average": 520850,
    "median": 497900
  },
  "engagement_rate_by_followers": 0.022,
  "engagement_rate_by_views": 4.0736,
  "posts_per_week": 2.07,
  "posting_times": {
    "timezone": "Europe/Istanbul",
    "metric": "engagement",
    "posts": 20,
    "by_weekday": [
      {
        "weekday": "monday",
        "posts": 1,
        "average_engagement": 22016
      },
      {
        "weekday": "tuesday",
        "posts": 3,
        "average_engagement": 12856
      }
    ],
    "by_hour": [
      {
        "hour": 0,
        "posts": 1,
        "average_engagement": 15278
      },
      {
        "hour": 1,
        "posts": 1,
        "average_engagement": 21384
      }
    ],
    "best_weekday": "wednesday",
    "best_hour": 20,
    "best_slot": {
      "weekday": "thursday",
      "hour_from": 18,
      "hour_to": 21
    },
    "min_posts": 2
  },
  "formula_version": 2,
  "formulas": {
    "average": "total / posts, over the sampled posts that have the value",
    "median": "the middle value of the sampled posts that have the value; the mean of the two middle values when their number is even",
    "engagement_rate_by_followers": "100 * average(likes + comments) / followers, over the sampled posts whose likes and comments are both known; null when followers is 0 or unknown",
    "engagement_rate_by_views": "100 * sum(likes + comments) / sum(views), over the sampled posts whose likes, comments and views are all known; null when that sum of views is 0",
    "posts_per_week": "(sample.posts - 1) / ((sample.to - sample.from) in days / 7); null with fewer than 2 posts or when they share one timestamp",
    "posting_times": "engagement = likes + comments of each sampled post whose likes, comments and exact time are known (a time worked back from \"3 weeks ago\" is not); each such post counts in its weekday, its hour and its weekday's 3-hour slot (00-03, 03-06, ... 21-24) in the asked time zone; average_engagement = total engagement / posts of the bucket, null without posts; best_weekday, best_hour, best_slot = the highe…"
  }
}

Tüm uç noktalarda ortak

Her rota bunları döndürebilir: eksik ya da hatalı anahtar, biten kredi, yanıt vermeyen platform ya da bizim tarafımızdaki bir hata. Hiçbiri kredi harcamaz.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

05Notlar

Bize ait bir endpoint: ScrapeCreators'ta analiz endpoint'i yok. Yanıt: `platform`, `owner` (`id`, `username`, `display_name`), `followers`, `sample` (`posts`, ISO 8601 UTC biçiminde `from` ve `to`, `posts_read`, `pinned_excluded`, `reposts_excluded`), `likes`, `comments` ve `views` (her biri `posts`, `missing`, `total`, `average`, `median`), `engagement_rate_by_followers` = 100 × ortalama(beğeni + yorum) / takipçi, `engagement_rate_by_views` = 100 × toplam(beğeni + yorum) / toplam(görüntülenme), `posts_per_week`, `formula_version` ve `formulas` (tüm formüller metin olarak). Sabitlenmiş gönderiler ve yeniden paylaşımlar örnekleme alınmaz. Platformun vermediği bir sayı (gizli beğeni, bir fotoğrafın görüntülenmesi) 0 sayılmaz, dışarıda bırakılır ve `missing` içinde sayılır; takipçi ya da görüntülenme 0 veya bilinmiyorsa oran `null` olur. Gönderisi olmayan bir hesap, profiliyle ve boş bir örneklemle yanıtlanır. TikTok'un web'deki 10.000'in üzerindeki beğeni ve oynatma sayıları yüzlüğe yuvarlanmıştır. Gizli hesap ücretsiz 403, bulunamayan hesap ücretsiz 404 döner. `posting_times` (formula_version 2), örneklenen gönderilerin en çok etkileşimi hangi zamanlarda aldığını `tz` ile verilen saat diliminde gösterir; aynı gönderilerden hesaplanır, ek ücreti yoktur: `timezone`, `metric` (`engagement` = bir gönderinin beğeni + yorum sayısı), `posts` (iki sayısı ve zamanı bilinen örneklem gönderileri), `by_weekday` (pazartesiden pazara) ve `by_hour` (0–23), her öğede `posts` ve `average_engagement` (gönderi yoksa null), ardından `best_weekday`, `best_hour`, `best_slot` (`weekday`, `hour_from`, `hour_to`: sabit 3 saatlik aralıklardan biri, 00–03 … 21–24) ve `min_posts`. En iyi dilim, en az `min_posts` (2) gönderisi olan dilimler arasında ortalaması en yüksek olandır; eşitlikte gönderisi çok olan, sonra daha erken olan seçilir; yeterli gönderisi olan dilim yoksa null. Gün × saat tablosu yoktur: 12–50 gönderi için 168 hücre tek tek gönderileri anlatırdı. Bu kadar küçük bir örneklem bir ipucudur, bir paylaşım takvimi değil.

06Hatalar ve krediler

Her hatada success: false ve gerçek bir HTTP durum kodu döner; kredi düşmez.

  • 400missing_parameter

    Zorunlu bir parametre eksik veya geçersiz.

  • 403private_account

    Hesap gizli ya da yaş kısıtlamalı.

  • 404not_found

    Böyle bir hesap yok.

  • 503upstream_error

    Platform şu an cevap vermiyor; tekrar deneyin.