Respons AI

API + MCP

POST/v3/brand-radar/ai-responses

Permintaan ke endpoint ini akan menghabiskan unit API berdasarkan parameter prompts: permintaan yang hanya mengembalikan data prompt kustom gratis, sedangkan permintaan yang menyertakan data prompt Ahrefs mengikuti penetapan harga unit API Standard.

Isi permintaan

selectarray<string>Required

Daftar kolom untuk dikembalikan.

Example:["field_a","field_b"]

whereobject

Ekspresi filter. Pengenal kolom berikut dikenali (ini berbeda dari pengenal yang dikenali oleh parameter select).

report_idstring

ID laporan yang akan digunakan. Jika ID diberikan, parameter lainnya diambil dari laporan (brand, competitors, market, country, filters). Jika country atau filters disediakan, parameter tersebut akan menggantikan yang ada di laporan. Anda dapat menemukannya di URL laporan Brand Radar Anda di Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Daftar nama merek dan situs web yang akan dicari.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nama merek/pesaing

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Domain target

Example:ahrefs.com

scopestringrequired

Cakupan target.

Nilai yang diizinkan:urlpathdomainsubdomains

competitorsarray<object>

Daftar nama kompetitor dan situs web yang akan dicari.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nama merek/pesaing

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Domain target

Example:ahrefs.com

scopestringrequired

Cakupan target.

Nilai yang diizinkan:urlpathdomainsubdomains

content_filterobject

Frasa opsional yang digunakan untuk menyertakan atau mengecualikan hasil berdasarkan kontennya.

includearray<string>

Hanya tampilkan hasil yang berisi setidaknya salah satu dari frasa yang sama persis berikut.

excludearray<string>

Sembunyikan hasil yang berisi salah satu dari frasa yang sama persis berikut.

data_sourcearray<string>Required

Daftar model chatbot. Semua model dapat dikombinasikan satu sama lain. Modul claude hanya mendukung prompt kustom.
Model google_ai_overviews_keywords dan google_ai_mode_keywords melaporkan visibilitas AI Overviews / AI Mode yang diperoleh dari kueri pencarian Google (kata kunci), bukan dari prompt.

Nilai yang diizinkan:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

Daftar kode negara dua huruf (ISO 3166-1 alpha-2).

Nilai yang diizinkan:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Jenis prompt yang akan digunakan. Jika tidak ditentukan, keduanya akan digunakan. Prompt kustom mengharuskan report_id disertakan.

Nilai yang diizinkan:ahrefscustom

limitinteger

Jumlah hasil yang akan dikembalikan.

Default:1000

datestring (date)

Tanggal yang akan dicari dalam format YYYY-MM-DD.

date_comparedstring (date)

Tanggal untuk dibandingkan dengan date, dalam format YYYY-MM-DD. Harus benar-benar lebih awal daripada date. Jika diatur, laporan mencakup setiap prompt yang dijawab pada salah satu tanggal tersebut, dan kolom status melaporkan bagaimana masing-masing berubah di antara keduanya. Prompt yang hanya dijawab pada date_compared dilaporkan sebagai lost, dan kolom lainnya menjelaskan responsnya pada date_compared, karena tidak memiliki respons pada date.

order_by

Cara mengurutkan hasil: berdasarkan kolom, atau berdasarkan cara respons membahas satu brand, seperti yang bisa dilakukan halaman Sentiment di Brand Radar.

Kolom untuk mengurutkan hasil berdasarkan kolom tersebut.

Nilai yang diizinkan:relevancevolume

tags_filterobject

Ekspresi filter untuk tag prompt. Memerlukan report_id. Menggunakan sintaks filter dengan batasan berikut: satu-satunya nama field yang valid adalah "tag"; operator yang valid hanyalah: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; kedalaman nesting maksimum untuk and dan or adalah 2.

Example:{ "or": [ { "field": "tag", "is": [ "eq", "branded" ] }, { "field": "tag", "is": [ "eq", "competitor" ] } ] }

brand_filterobject

Ekspresi filter untuk visibilitas merek Anda, yang mencerminkan filter “Your brand”. brand_name mencocokkan respons berdasarkan apakah respons tersebut menyebutkan merek Anda: "mentioned" atau "not_mentioned". page_status mencocokkan berdasarkan cara AI menggunakan halaman Anda: "cited" (AI mengambil halaman dari situs Anda dan merujuknya dalam jawaban), "found_but_not_cited" (AI mengambil halaman dari situs Anda sebagai sumber potensial, tetapi tidak merujuknya dalam jawaban akhir), atau "not_found" (AI tidak mengambil halaman apa pun dari situs Anda).
Menggunakan sintaks filter dengan batasan berikut: satu-satunya operator yang valid adalah "eq"; setiap field adalah satu bagian: berikan satu nilai, atau gabungkan beberapa nilai dari field yang sama dengan or; gabungkan bagian brand_name dan page_status dengan and/or tingkat teratas. Memilih semua nilai dari sebuah field akan ditolak karena cocok dengan semuanya (abaikan field tersebut).

Example:{ "and": [ { "field": "brand_name", "is": [ "eq", "mentioned" ] }, { "or": [ { "field": "page_status", "is": [ "eq", "cited" ] }, { "field": "page_status", "is": [ "eq", "found_but_not_cited" ] } ] } ] }

volume_rangeobject

Rentang volume yang akan difilter.

frominteger

tointeger

changesobject

Memerlukan date_compared. Hanya menyimpan prompt yang berubah dengan salah satu cara yang dipilih di sini. Ketiga kolom digabungkan dengan logika OR satu sama lain, demikian pula nilai di dalam tiap kolom, sehingga kolom yang dihilangkan atau kosong tidak menambahkan apa pun ke filter, dan objek yang sepenuhnya kosong akan mempertahankan semua prompt.

promptarray<string>

Simpan prompt yang dijawab hanya pada salah satu dari dua tanggal (new, lost) atau pada keduanya (no_change).

Nilai yang diizinkan:newlostno_change

mentionsarray<string>

Simpan prompt ketika kumpulan brand milik Anda yang disebutkan dalam respons bertambah satu brand (new), berkurang satu (lost), atau identik pada kedua tanggal (no_change). Kompetitor tidak diperhitungkan.

Nilai yang diizinkan:newlostno_change

citationsarray<string>

Simpan prompt ketika kumpulan domain milik Anda yang dikutip oleh respons bertambah satu domain (new), berkurang satu (lost), atau identik pada kedua tanggal (no_change). Kompetitor tidak diperhitungkan.

Nilai yang diizinkan:newlostno_change

sentiment_filterobject

Filter untuk cara respons membahas brand dan kompetitor Anda, seperti filter Sentimen di Brand Radar. Menggunakan sintaks filter dengan tiga kolom:

Field yang tersedia:

brand (wajib): nama dari brands atau competitors, dengan "eq".
sentiment (opsional): positive, neutral, negative atau mixed. Dengan "eq", brand disebutkan dengan sentimen ini. Dengan "neq", brand disebutkan dengan suatu sentimen, tetapi tidak pernah yang ini. Dengan "empty", brand tidak pernah disebutkan dengan sentimen, yang mencakup respons yang tidak menyebutkannya. Dengan not "empty", brand disebutkan dengan suatu sentimen. Tanpa sentiment, setiap respons yang menyebutkan brand akan cocok.
aspect (opsional): sentimen tersebut tentang apa, dengan "eq": features_specs, performance_effectiveness, price_value, reputation_popularity, quality_reliability, design_comfort, usability_compatibility, availability_delivery, safety_health, service_support atau general.
Setiap aturan berlaku untuk satu brand: satu kondisi, atau and dari beberapa kondisi. Untuk menggabungkan aturan, letakkan masing-masing dalam and-nya sendiri dan gabungkan dengan and atau or pada tingkat teratas.

Example:{ "or": [ { "and": [ { "field": "brand", "is": [ "eq", "Adidas" ] }, { "field": "sentiment", "is": [ "eq", "negative" ] } ] }, { "and": [ { "field": "brand", "is": [ "eq", "Nike" ] }, { "field": "sentiment", "is": [ "eq", "positive" ] }, { "field": "aspect", "is": [ "eq", "price_value" ] } ] } ] }

opinions_firstboolean

Menempatkan respons yang berisi penyebutan positif, negatif, atau campuran tentang brand yang dilacak di depan yang lainnya, tiap grup diurutkan berdasarkan relevansi, seperti daftar pada halaman Sentimen di Brand Radar. Hanya dengan order_by relevance.

Default:false

outputstring

Format output.

Nilai yang diizinkan:jsonphp

Respons

ai_responsesarray<object>

brand_sentimentarray<object>

Setiap penyebutan brand yang dilacak dalam respons—brand Anda terlebih dahulu lalu kompetitor sesuai urutannya—beserta bagaimana respons membahasnya.

brandstring

Brand yang dilacak dan disebutkan.

sentimentstring or null

Bagaimana respons membahas brand pada penyebutan ini. Null bila tidak tersedia.

Nilai yang diizinkan:positiveneutralnegativemixednull

aspectstring or null

Penyebutan ini tentang apa, misalnya harga atau kualitas. Null bila tidak tersedia.

Nilai yang diizinkan:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull

snippetstring or null

Kalimat di sekitar penyebutan. Null bila tidak dapat ditemukan dalam respons.

countrystring

Negara dari pertanyaan tersebut.

data_sourcestring

Model chatbot yang menghasilkan respons.

funnel_stagestring or null

Tahap funnel dari prompt. Bernilai null saat tidak ada tahap funnel yang tersedia.

Nilai yang diizinkan:awarenessconsiderationdecisionunclearnull

intentarray<string>

Label maksud prompt, termasuk maksud utamanya, subtipe, dan atribut bermerek/lokal. Array kosong berarti tidak ada label maksud yang tersedia.

Nilai yang diizinkan:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation

last_updatedstring (date)

Tanggal saat data terakhir kali diperbarui.

linksarray<object>

(10 unit) Tautan yang digunakan untuk respons.

urlstring

titlestring or null

questionstring

Pertanyaan yang diajukan oleh pengguna.

responsestring

(10 unit) Respons dari model.

search_queriesarray<string>

Kueri pencarian yang digunakan chatbot untuk menemukan informasi untuk respons. Catatan: jika data_source tidak mencakup chatgpt atau perplexity, kolom ini akan selalu kosong.

statusstring or null

Bagaimana prompt berubah antara date_compared dan date. Null kecuali date_compared ditetapkan. new — dijawab pada date tetapi tidak pada date_compared. lost — dijawab pada date_compared tetapi tidak pada date; sisa baris ini menjelaskan respons date_compared, karena tidak ada respons pada date. no_change — dijawab pada kedua tanggal, yang tidak mengatakan apa pun tentang apakah respons itu sendiri, penyebutannya, atau kutipannya berubah.

Nilai yang diizinkan:newlostno_changenull

tagsarray<string>

Tag yang ditetapkan pada kueri.

volumeinteger

(10 unit) Perkiraan volume pencarian bulanan. Ini didasarkan pada perkiraan kami untuk Google, dengan menggabungkan volume pencarian kata kunci terkait di mana pertanyaan ini muncul di bagian People Also Ask.