İçeriğe geç
Kostoway

API belgeleri

GET /v1/domains/semrush.com/overview isteği, o alan adının Semrush otorite puanını, trafiğini ve backlink sayılarını JSON olarak döner ve 1 kredi harcar. Backlinkler, anahtar kelimeler, rakipler, referans alan adları ve trafik geçmişi aynı yolun altındadır.

Temel adres https://api.ornek.com
Alan adı özeti
Otorite puanı, organik ve ücretli trafik, anahtar kelime, referans alan adı ve backlink sayıları. 1 kredi.
Listeler
Backlinkler, organik anahtar kelimeler ve referans alan adları 100 satırlık sayfalar halinde; rakipler ve aylık trafik geçmişi.
Toplu özet
50 alan adına kadar özet tek istekle, arka planda çalışan bir iş olarak. Alan adı başına 1 kredi.
Sandbox
sm_test_kostoway anahtarıyla ücretsiz dene; bu sayfadaki örnekler onunla hemen çalışır. Ayrıntılar.
  • Yanıtlar UTF-8 JSON'dur. Zaman damgaları ISO 8601 biçiminde ve UTC'dir: 2026-11-15T08:15:08Z.
  • Hatalarda error.code alanına göre dallan; mesajlar insanlar içindir ve değişebilir.
  • Kalan kredini ve kullanımını /v1/me ile ücretsiz görürsün. Makine tarafından okunabilir tanım OpenAPI belgesinde.

Hızlı başlangıç

Anahtar almaktan ilk yanıta üç adım.

  1. Sandbox anahtarıyla hemen dene, sonra paket al. Herkese açık sm_test_kostoway anahtarı semrush.com ve getkosto.com için ücretsiz çalışır; bu sayfadaki bütün örnekler ve Dene panelleri onunla hazır gelir. Kendi alan adların için kredi paketlerinden birini kayıt sayfasından Telegram üzerinden satın al; anahtarın Telegram'dan gelir.
  2. Uç noktayı çağır. Anahtarı X-API-Key başlığında gönder ve /v1/domains/{alan-adı}/overview adresine istek at. Örnek seçtiğin dilde hazır; paket aldıktan sonra sandbox anahtarını kendi anahtarınla değiştir.
  3. JSON'u oku. metrics nesnesi otorite puanını, trafiği ve backlink sayılarını içerir. Harcanan ve kalan kredi her yanıttaki credits nesnesinde ve X-Credits-* başlıklarında yazar.

Her uç noktanın altındaki Dene panelinden isteği doğrudan bu sayfadan gönderebilirsin. Anahtar yalnızca bu tarayıcıda kalır ve istek sen düğmeye basmadan gitmez.

Sandbox

Paket almadan önce API'yi kendi kodunda denemek için herkese açık bir anahtar var: sm_test_kostoway. Bu sayfadaki örnekler ve Dene panelleri varsayılan olarak bu anahtarla gelir.

  • Yalnızca semrush.com ve getkosto.com için, yalnızca /v1/domains/… uç noktalarında çalışır. Başka bir alan adı 422 sandbox_domain döner.
  • Ücretsizdir: credits.charged her zaman 0, X-Credits-Remaining başlığı sandbox, gövdede "sandbox": true.
  • Yalnızca önbellekten okur; önbellekte olmayan bir istek 503 upstream_busy döner. fresh=true etkisizdir.
  • IP adresi başına dakikada 10 istek. Eski yollar ve toplu işler 403 sandbox_not_allowed döner.
  • /v1/me sandbox profilini döner: status: "sandbox", allowed_domains, rate_limit_per_minute.

Kimlik doğrulama

/health, /v1/plans, /v1/quote ve /v1/changelog dışındaki her uç nokta bir API anahtarı ister. Anahtarı X-API-Key başlığında gönder (OpenAPI'deki güvenlik şeması: ApiKey). Anahtarlar sm_ ile başlar.

YöntemDurum
X-API-Key: sm_… başlığıÖnerilen ve desteklenen yol.
?api_key=sm_… parametresiEskidi; hâlâ çalışır ama adres satırındaki anahtar kayıtlara ve geçmişe sızar. Kullanma.
  • Anahtar yoksa 401 missing_api_key, geçersizse 401 invalid_api_key döner; ikisinde de WWW-Authenticate: ApiKey başlığı bulunur. /v1/me geçersiz anahtara 403 invalid_api_key ile yanıt verir.
  • İptal edilen anahtar 403 key_revoked, süresi dolan anahtar 403 key_expired alır.
  • Her anahtar dakikada en fazla 30 istek gönderebilir (429 rate_limited, Retry-After kadar bekle). Bazı anahtarlarda ek bir günlük sınır olabilir (429 daily_limit_reached).
  • Kalan kredini ve bitiş tarihini giriş yaptıktan sonra kontrol panelinde ya da /v1/me ile görürsün.

Krediler ve fiyatlar

API kredi ile çalışır. Her veri isteği türüne göre belirli sayıda kredi harcar; harcanan ve kalan kredi her yanıttaki credits nesnesinde ve X-Credits-Charged / X-Credits-Remaining başlıklarında yazar.

İstekKrediDurum
  • Krediler paketler halinde satılır; paketleri fiyatlar bölümünde görür, kayıt sayfasından Telegram üzerinden satın alırsın.
  • Krediler satın alındıktan sonra 90 gün geçerlidir. Yeni bir paket kredilerini artırır ve geçerlilik süresini uzatır.
  • Önbellekten dönen yanıtlar da kredi harcar. Sayfalı istekler sayfa başına, toplu özet benzersiz alan adı başına ücretlendirilir.
  • 502 ve 503 ile biten istekler kredi harcamaz; düşülen kredi otomatik iade edilir.
  • /v1/me, /v1/plans, /v1/quote, /v1/changelog, /v1/bulk/{job_id} ve /health ücretsizdir; sandbox anahtarı da ücretsizdir. Kredi bittiğinde veri istekleri 402 insufficient_credits döner.

Özel miktar

Paketlerden büyük bir miktar istersen 7.500 ile 100.000 kredi arasında, 500'lük adımlarla özel teklif alabilirsin. Kredi başı fiyat miktar büyüdükçe düşer; kademeler /v1/plans yanıtındaki custom.tiers alanındadır. Fiyatı GET /v1/quote?credits=10000 ile hesaplatırsın.

BaşlangıçKredi başı oran

Yanıt yapısı

Bütün veri yanıtları aynı ortak alanlarla gelir; listeler ayrıca bir pagination nesnesi taşır. Uç noktaların alan tablolarında yalnızca kendilerine özgü alanlar yazıyor.

Sayfalama

Backlinkler, anahtar kelimeler ve referans alan adları page parametresiyle 100 satırlık sayfalar halinde gelir (1–100). Rakipler ve trafik geçmişi tek sayfadır ama aynı pagination nesnesini taşır. has_more false olana kadar page değerini artırabilirsin; her sayfa ayrı istektir.

Başlıklar

Yanıt başlıkları gövdedeki bilgiyi tekrar eder; gövdeyi açmadan kredi ve hız durumunu izlemek için kullanabilirsin. Destek isterken X-Request-Id değerini paylaş.

BaşlıkNe zamanAnlamı

İstek başlıkları

  • X-API-Key: API anahtarın.
  • Idempotency-Key: yalnızca toplu istekte, isteğe bağlı. Aynı anahtarla 24 saat içinde gelen aynı istek yeni iş açmaz ve ikinci kez ücret almaz.
  • Content-Type: application/json: gövdeli isteklerde (toplu istek).

Önbellek ve süreler

Her alan adı için çekilen sonuç diskte kalıcı olarak saklanır ve sunucu yeniden başlasa da korunur. Önbellekten dönen yanıtta cached: true, X-Cache: HIT ve verinin kaydedildiği cached_at bulunur.

  • Güncel veri istiyorsan fresh=true gönder. Önbellekteki kopya 6 saatten eskiyse veri Semrush'tan yeniden çekilir; daha yeniyse önbellekteki kopya döner. Hangisinin olduğunu yanıttaki fresh_applied söyler.
  • Önbellekten dönen yanıtlar da kredi harcar.

İstemci zaman aşımını en az 120 saniye yap. Önbellekte olmayan bir alan adında veri Semrush'tan canlı çekilir ve 10–90 saniye sürebilir. Sunucu 110 saniyede vazgeçer, 503 upstream_timeout döner ve krediyi iade eder.

Ülke veritabanları

db parametresi Semrush'ın ülke veritabanını seçer. Alan adı özetinde ve toplu özette boş bırakırsan tüm ülkelerin toplamı (global) döner; anahtar kelime, rakip ve geçmiş isteklerinde varsayılan us'dir. Listede olmayan bir kod 422 unsupported_db döner.

Hata kodları

Hatalar HTTP durum koduyla ve hep aynı gövdeyle gelir. Programın error.code alanına göre dallanmalı; message insanlar içindir ve değişebilir. details yalnızca bazı doğrulama hatalarında bulunur. Eski istemciler için aynı mesaj üst düzeydeki detail alanında da durur.

DurumKodNe zaman, ne yapmalı
  • 502 ve 503 bizim taraftaki geçici durumlardır ve kredi harcamaz; Retry-After varsa o kadar bekleyip aynı isteği yinele.
  • 402, 403, 409 ve 422 yanıtlarını aynı istekle yineleme; isteği ya da anahtarı düzelt veya kredi al.

Kod örnekleri

Hata yönetimi ve uzun zaman aşımıyla, üretimde kullanmaya hazır örnekler. Dil seçimi tüm sayfa için geçerlidir ve hatırlanır.

  • Anahtarı koda yazma; ortam değişkeninden oku.
  • Zaman aşımını en az 120 saniye tut.
  • error.code değerine göre dallan; upstream_* kodlarında Retry-After kadar bekleyip yeniden dene. Destek isterken request_id değerini paylaş.

Eski yollar

İlk sürümdeki yollar hâlâ çalışır ve aynı yanıtı döner, ama eskidi ve 1 Temmuz 2027'de kapanacak. Yanıtlarında Deprecation: true, Sunset: Wed, 01 Jul 2027 00:00:00 GMT ve yeni yolu gösteren Link: <…>; rel="successor-version" başlıkları bulunur. Sandbox anahtarı eski yollarda çalışmaz (403 sandbox_not_allowed).

EskiYeniKapanış
/domain/{alan-adı}/v1/domains/{alan-adı}/overview1 Temmuz 2027
/backlinks/{alan-adı}/v1/domains/{alan-adı}/backlinks1 Temmuz 2027
/keywords/{alan-adı}/v1/domains/{alan-adı}/keywords1 Temmuz 2027
/competitors/{alan-adı}/v1/domains/{alan-adı}/competitors1 Temmuz 2027
/refdomains/{alan-adı}/v1/domains/{alan-adı}/refdomains1 Temmuz 2027
/history/{alan-adı}/v1/domains/{alan-adı}/history1 Temmuz 2027
?api_key=sm_…X-API-Key: sm_… başlığıEskidi

Değişiklik günlüğü

Sürümler ve önemli değişiklikler. Aynı liste makine tarafından okunabilir biçimde GET /v1/changelog adresinde.

Swagger ve OpenAPI

Tüm uç noktaların OpenAPI tanımı ve otomatik oluşturulan etkileşimli arayüz Swagger üzerindedir. Swagger'daki sunucu seçicisi canlı API adresini gösterir; istekleri oradan da deneyebilirsin. İstemci kodu üretmek için ham şemayı kullan.