AI の応答

API + MCP

POST/v3/brand-radar/ai-responses

このエンドポイントへのリクエストは、prompts パラメータに基づいてAPIユニットを消費します。カスタムプロンプトのデータのみを返すリクエストは無料ですが、Ahrefsのプロンプトデータを含むリクエストはスタンダードのAPIユニット料金が適用されます。

リクエスト本文

selectarray<string>Required

返却するフィールドのリストです。

Example:["field_a","field_b"]

whereobject

フィルター式。次の列識別子が認識されます（select パラメータで認識される識別子とは異なります）。

report_idstring

使用するレポートのIDです。指定した場合、他のパラメータ（ブランド、競合、マーケット、国、フィルター）はレポートから取得されます。country または filters を指定すると、レポート内の設定よりも優先されます。Ahrefs のブランドレーダーのレポートURLで確認できます: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

検索対象のブランド名および Web サイトのリスト。

Default:[]

At least one of names or url_groups is required

namesarray<string>

ブランド／競合他社の名称

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

url_groupsarray<object>

targetstring (domain)required

ターゲットのドメイン

Example:ahrefs.com

scopestringrequired

ターゲットのスコープ。

許可される値:urlpathdomainsubdomains

competitorsarray<object>

検索対象の競合名および Web サイトのリスト。

Default:[]

At least one of names or url_groups is required

namesarray<string>

ブランド／競合他社の名称

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

url_groupsarray<object>

targetstring (domain)required

ターゲットのドメイン

Example:ahrefs.com

scopestringrequired

ターゲットのスコープ。

許可される値:urlpathdomainsubdomains

content_filterobject

内容に基づいて結果を含めたり除外したりするために使用する任意のフレーズ。

includearray<string>

これらの完全一致フレーズのうち、少なくとも1つを含む結果のみを表示します。

excludearray<string>

これらの完全一致フレーズのいずれかを含む結果を非表示にします。

data_sourcearray<string>Required

チャットボットモデルのリスト。すべてのモデルを相互に組み合わせて使用できます。claude モジュールはカスタムプロンプトのみに対応しています。
google_ai_overviews_keywords と google_ai_mode_keywords の各モデルは、プロンプトではなく Google 検索クエリ（キーワード）に基づく、AIによる概要 / AI モードでの表示状況をレポートします。

許可される値:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

2 文字の国コード（ISO 3166-1 alpha-2）のリスト。

許可される値:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

使用するプロンプトの種類。指定されていない場合は両方が使用されます。カスタムプロンプトを使用するには report_id を指定する必要があります。

許可される値:ahrefscustom

limitinteger

返す結果の数です。

Default:1000

datestring (date)

検索対象の日付（YYYY-MM-DD 形式）。

date_comparedstring (date)

date と比較する日付（YYYY-MM-DD 形式）。date より厳密に前の日付である必要があります。設定すると、レポートにはいずれかの日付で回答されたすべてのプロンプトが含まれ、status フィールドにはそれぞれが両日間でどのように変化したかが表示されます。date_compared のみに回答があるプロンプトは lost としてレポートされ、それ以外のフィールドには date に回答が存在しないため date_compared のレスポンスが記述されます。

order_by

結果の並べ替え方法です。列で指定するか、ブランドレーダーのセンチメントページのように、1つのブランドについての回答の言及内容で並べ替えます。

結果の並び替えに使用する列。

許可される値:relevancevolume

tags_filterobject

プロンプトタグ用のフィルター式です。report_id が必要です。次の制約のもとでフィルター構文を使用します。有効なフィールド名は "tag" のみです。有効な演算子は "eq"、"neq"、"substring"、"isubstring"、"phrase_match"、"iphrase_match"、"prefix"、"suffix"、"empty" のみです。and、or の最大ネストの深さは2です。

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

brand_filterobject

「あなたのブランド」フィルターを反映した、ブランドの可視性に関するフィルター式です。brand_name は、回答内でブランドに言及されているかどうか（"mentioned" または "not_mentioned"）に一致します。page_status は、AI があなたのページをどのように使用したか（"cited"（AI があなたのサイトのページを取得し、回答内で参照した）、"found_but_not_cited"（AI があなたのサイトのページを候補ソースとして取得したが、最終回答では参照しなかった）、"not_found"（AI があなたのサイトのページを一切取得しなかった））に一致します。
次の制約のもとでフィルター構文を使用します。有効な演算子は "eq" のみです。各フィールドを1つのセクションとして扱います。単一の値を指定するか、同じフィールドの複数の値を or で組み合わせてください。brand_name セクションと page_status セクションは、トップレベルの and/or で結合してください。フィールドのすべての値を選択すると、すべてに一致してしまうため拒否されます。代わりに、そのフィールドを省略してください。

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

フィルタリングに使用するボリューム範囲。

frominteger

tointeger

changesobject

date_compared が必要です。ここで選択したいずれかの方法で変化したプロンプトのみを残します。3つの列は互いにORで結合され、各列内の値もORで結合されます。そのため、列を省略するか空にしてもフィルターには何も追加されず、オブジェクト全体が完全に空の場合はすべてのプロンプトが残ります。

promptarray<string>

2つの日付のうち片方でのみ回答されたプロンプト（new、lost）または両方で回答されたプロンプト（no_change）を残します。

許可される値:newlostno_change

mentionsarray<string>

応答内で言及されている自社ブランドの集合に、ブランドが追加された（new）、減った（lost）、または両日で同一（no_change）となったプロンプトを残します。競合は考慮されません。

許可される値:newlostno_change

citationsarray<string>

応答で引用された自社ドメインの集合に、ドメインが追加された（new）、減った（lost）、または両日で同一（no_change）となったプロンプトを残します。競合は考慮されません。

許可される値:newlostno_change

sentiment_filterobject

回答が自社ブランドと競合についてどのように述べているかを絞り込むためのフィルターです。ブランドレーダーのセンチメントフィルターのように機能します。3つのフィールドを使う filter 構文を使用します。

利用可能なフィールド:

brand（必須）：brands または competitors に含まれる名前。"eq" を指定します。
sentiment（任意）：positive、neutral、negative、mixed。"eq" の場合、そのブランドはこのセンチメントで言及されます。"neq" の場合、そのブランドは何らかのセンチメントで言及されますが、このセンチメントでは言及されません。"empty" の場合、そのブランドはセンチメント付きで一度も言及されず、言及がない回答も含まれます。not "empty" の場合、そのブランドは何らかのセンチメントで言及されます。sentiment を指定しない場合、ブランドに言及しているあらゆる回答が一致します。
aspect（任意）：どの側面についてのセンチメントかを "eq" で指定します。features_specs、performance_effectiveness、price_value、reputation_popularity、quality_reliability、design_comfort、usability_compatibility、availability_delivery、safety_health、service_support、general。
各ルールは1つのブランドに関するものです。1つの条件、または条件を and で結合したものになります。ルールを組み合わせるには、それぞれを個別の and に入れ、トップレベルの and または or で結合してください。

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

ブランドレーダーのセンチメントページでの一覧と同様に、追跡中ブランドの肯定的・否定的・混合のメンションを含む回答を、それ以外より先に表示します（各グループ内は関連度順）。order_by が relevance の場合のみ使用できます。

Default:false

outputstring

出力形式。

許可される値:jsonphp

応答

ai_responsesarray<object>

brand_sentimentarray<object>

回答内にある追跡中ブランドのすべてのメンション（自社ブランドを先に、その後に競合を指定順で）と、それについて回答がどのように述べているか。

brandstring

言及されている追跡中のブランド。

sentimentstring or null

このメンションで、回答がブランドについてどのように述べているか。利用できない場合は null です。

許可される値:positiveneutralnegativemixednull

aspectstring or null

価格や品質など、このメンションが何についてのものか。利用できない場合は null です。

許可される値:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull

snippetstring or null

メンションの前後の文。回答内で見つけられない場合は null です。

countrystring

質問の国。

data_sourcestring

回答を生成したチャットボットモデル。

funnel_stagestring or null

プロンプトのファネルステージ。ファネルステージが利用できない場合は null になります。

許可される値:awarenessconsiderationdecisionunclearnull

intentarray<string>

プロンプトの意図ラベル（主な意図、サブタイプ、ブランド／ローカル属性など）です。空の配列は、利用可能な意図ラベルがないことを意味します。

許可される値:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation

last_updatedstring (date)

データが最後に更新された日付。

linksarray<object>

（10ユニット）回答に使用されたリンク。

urlstring

titlestring or null

questionstring

ユーザーが尋ねた質問。

responsestring

(10単位) モデルからの応答。

search_queriesarray<string>

チャットボットが応答のための情報を探す際に使用した検索クエリ。注：data_source に chatgpt または perplexity が含まれない場合、このフィールドは常に空になります。

statusstring or null

date_compared と date の間でプロンプトがどのように変化したか。date_compared が設定されていない場合は null です。new — date では回答されたが date_compared では回答されなかった。lost — date_compared では回答されたが date では回答されなかった。date には回答がないため、この行の残りは date_compared の応答内容を示します。no_change — 両日とも回答された。これは応答自体、言及、引用が変化したかどうかについては何も示しません。

許可される値:newlostno_changenull

tagsarray<string>

クエリに付与されたタグ。

volumeinteger

(10単位) 推定月間検索数（検索ボリューム）。Google に関する当社推定に基づき、この質問が People Also Ask セクションに表示される関連キーワードの検索ボリュームを合算して算出しています。