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입니다. ID가 제공되면 다른 파라미터(brand, competitors, market, country, filters)는 보고서에서 가져옵니다. country 또는 filters가 제공되면 보고서의 값을 덮어씁니다. Ahrefs의 브랜드 레이더 보고서 URL에서 확인할 수 있습니다: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

검색할 브랜드 이름과 웹사이트 목록입니다.

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>

검색할 경쟁사 이름과 웹사이트 목록입니다.

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>

다음의 정확히 일치하는 문구 중 하나 이상을 포함하는 결과만 표시합니다.

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>

두 글자 국가 코드(ISO 3166-1 alpha-2) 목록입니다.

허용되는 값:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

사용할 프롬프트 유형입니다. 지정하지 않으면 둘 다 사용됩니다. 사용자 정의 프롬프트를 사용하려면 report_id를 제공해야 합니다.

허용되는 값:ahrefscustom

limitinteger

반환할 결과 수입니다.

Default:1000

datestring (date)

YYYY-MM-DD 형식으로 검색할 날짜입니다.

date_comparedstring (date)

YYYY-MM-DD 형식으로 date와 비교할 날짜입니다. date보다 반드시 이전이어야 합니다. 설정하면 보고서는 두 날짜 중 어느 날짜에든 응답된 모든 프롬프트를 포함하며, status 필드는 각 항목이 두 날짜 사이에서 어떻게 변경되었는지 보고합니다. date_compared에만 응답이 있고 date에는 없는 프롬프트는 lost로 보고되며, date의 응답이 없으므로 나머지 필드는 date_compared의 응답을 설명합니다.

order_by

결과 정렬 방식입니다. 열을 기준으로 정렬하거나, 브랜드 레이더의 감성 페이지에서처럼 응답이 한 브랜드를 어떻게 언급하는지를 기준으로 정렬할 수 있습니다.

결과를 정렬할 열입니다.

허용되는 값: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"뿐입니다. 각 필드는 하나의 섹션입니다. 단일 값을 지정하거나 같은 필드의 여러 값을 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가 필요합니다. 여기에서 선택한 방식 중 하나로 변경된 프롬프트만 유지합니다. 세 열은 서로 OR로 결합되며, 각 열 내의 값들도 OR로 결합됩니다. 따라서 생략되거나 비어 있는 열은 필터에 아무것도 추가하지 않으며, 객체가 완전히 비어 있으면 모든 프롬프트가 유지됩니다.

promptarray<string>

두 날짜 중 한 날짜에만 답변된 프롬프트(new, lost) 또는 두 날짜 모두에 답변된 프롬프트(no_change)를 유지합니다.

허용되는 값:newlostno_change

mentionsarray<string>

응답에서 언급된 자체 브랜드 집합에 브랜드가 추가됨(new), 제거됨(lost), 또는 두 날짜에서 동일함(no_change)이 발생한 프롬프트를 유지합니다. 경쟁사는 고려되지 않습니다.

허용되는 값:newlostno_change

citationsarray<string>

응답에서 인용된 자체 도메인 집합에 도메인이 추가됨(new), 제거됨(lost), 또는 두 날짜에서 동일함(no_change)이 발생한 프롬프트를 유지합니다. 경쟁사는 고려되지 않습니다.

허용되는 값:newlostno_change

sentiment_filterobject

응답이 내 브랜드와 경쟁사에 대해 어떻게 말하는지에 대한 필터로, 브랜드 레이더의 감성(Sentiment) 필터와 유사합니다. 세 가지 필드를 사용하는 필터 문법을 사용합니다:

사용 가능한 필드:

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.
각 규칙은 하나의 브랜드에 대한 것입니다. 하나의 조건이거나, 조건들의 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

브랜드 레이더의 감성(Sentiment) 페이지에서 나열하는 방식처럼, 추적 중인 브랜드가 긍정/부정/혼합으로 언급된 응답을 다른 응답보다 먼저 표시하고, 각 그룹 내에서는 관련도 기준으로 정렬합니다. 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 섹션에 표시되는 관련 키워드의 검색량을 합산해 산출합니다.