가이드 · 데이터 API
브레인드 데이터 API 안내
브레인드 데이터 API는 사내 대시보드, BI 도구, 데이터 적재 작업 같은 회사 프로그램이 브레인드에서 측정한 브랜드 지표를 JSON 형식으로 조회하는 기능입니다. 조회 결과는 브레인드 대시보드와 같은 기준으로 계산한 값입니다. 이 가이드는 API 키 발급부터 조회 6가지, 응답 형식, 오류 코드, 호출 한도까지 정리했습니다.
데이터 API는 Business 이상 요금제에서 제공합니다. 데이터 API로는 조회만 할 수 있으며, 검색어나 브랜드 설정을 추가하거나 변경할 수 없습니다.
데이터 API 시작 순서
- 조직의 소유자 또는 관리자가 「조직 설정 → API 키」에서 「새 키 발급」을 선택합니다. API 키는 2단계 인증을 등록한 계정으로만 발급할 수 있습니다.
- 키 이름, 조회할 브랜드, 유효 기간(90일·180일·1년)을 선택합니다.
- 발급 창에 표시된 API 키를 복사해 안전한 곳에 보관합니다. API 키는 이 창에서 한 번만 표시됩니다.
- 회사 프로그램에서 API 키를 Authorization 헤더에 담아 엔드포인트를 호출합니다.
다음은 명령줄 도구 curl로 브랜드 목록을 조회하는 예시입니다. 환경 변수 BRAIND_API_KEY에 발급한 API 키가 저장되어 있다고 가정합니다.
curl -H "Authorization: Bearer $BRAIND_API_KEY" \
"https://braind.pro/api/v1/brands"데이터 API 인증 방식
데이터 API는 모든 요청을 HTTP 헤더 「Authorization: Bearer {API 키}」 하나로 인증합니다. API 키는 brd_live_로 시작합니다.
- API 키를 URL의 쿼리 문자열에 넣으면 400 오류(key_in_url)로 거절합니다. URL은 서버와 중계 장비의 접속 기록에 남을 수 있으므로, 이 경우 그 키를 폐기하고 새로 발급해 주세요.
- 데이터 API는 회사 서버, BI 도구, 데이터 적재 작업처럼 웹 브라우저가 아닌 프로그램에서 호출합니다. 웹 브라우저에서 보낸 요청은 403 오류(browser_request_blocked)로 거절합니다. 웹페이지 코드에 넣은 API 키는 방문자 누구나 볼 수 있기 때문입니다.
- API 키는 발급한 사람이 아니라 조직에 속합니다. 발급한 구성원이 조직에서 제외되거나 탈퇴해도 키는 계속 동작하며, 「조직 설정 → API 키」 목록에 그 사실이 표시됩니다.
- API 키로 조회할 수 있는 브랜드는 발급할 때 선택한 브랜드뿐입니다. 발급한 뒤에 추가한 브랜드는 포함되지 않으므로, 조회할 브랜드를 바꾸려면 새 키를 발급합니다.
- 한 조직에서 동시에 사용할 수 있는 API 키는 최대 10개입니다.
데이터 API로 조회할 수 있는 데이터
데이터 API로 조회할 수 있는 데이터는 6가지입니다. 모든 조회는 GET 요청입니다. 브랜드별 조회는 엔드포인트의 {brand_id}로 브랜드를 지정하며, brand_id는 브랜드 목록 조회 결과에서 확인합니다.
| 엔드포인트 | 조회 | 내용 |
|---|---|---|
| /api/v1/brands | 브랜드 목록 | API 키로 조회할 수 있는 브랜드와 브랜드별 측정 플랫폼, 등록 검색어 수, 등록 경쟁사 |
| /api/v1/brands/{brand_id}/summary | 브랜드 성과 요약 | 브랜드 언급률, 첫 추천률, 평균 언급 순위, 자사 채널 출처 인용률과 직전 기간 대비 변화, 주별 브랜드 언급률 |
| /api/v1/brands/{brand_id}/keywords | 검색어별 결과 | 검색어별·플랫폼별 AI 답변 수, 브랜드 언급률, 자사 채널 출처 인용률, 평균 언급 순위, 감성별 답변 수 |
| /api/v1/brands/{brand_id}/sources | AI 답변 인용 출처 | 출처별 인용 수, 자사 채널·경쟁사 채널 여부, 플랫폼별 인용 수, 인용된 웹페이지 주소 예시 |
| /api/v1/brands/{brand_id}/competitors | 경쟁사 비교 | 자사와 등록 경쟁사의 브랜드 언급률, 평균 언급 순위, 출처 인용률, 브랜드 언급 점유율 |
| /api/v1/usage | 호출 사용량 | 이 API 키와 조직의 최근 24시간 호출 수와 한도 |
모든 엔드포인트의 기본 URL은 https://braind.pro/api/v1 입니다.
데이터 API 요청 파라미터
파라미터는 URL의 쿼리 문자열로 보냅니다. 조회마다 받는 파라미터가 정해져 있으며, 그 밖의 파라미터를 보내거나 같은 파라미터를 두 번 보내면 400 오류로 거절합니다. 파라미터 이름을 잘못 적었을 때 기본값이 적용되어 다른 기간의 숫자를 받는 일을 막기 위해서입니다.
| 파라미터 | 값 | 기본값 | 받는 조회 |
|---|---|---|---|
| start · end | 한국 시간 기준 날짜(YYYY-MM-DD). 양 끝 날짜를 포함하며, 기간은 최대 90일입니다. | 오늘을 포함한 최근 30일. start만 보내면 end는 오늘, end만 보내면 start는 end를 포함한 30일 전입니다. | 성과 요약 · 검색어별 결과 · 인용 출처 · 경쟁사 비교 |
| platform | 플랫폼 id 하나(아래 「플랫폼 id」 표). 지정하면 그 플랫폼의 결과만 조회합니다. | 측정 중인 모든 플랫폼 | 성과 요약 · 검색어별 결과 · 인용 출처 · 경쟁사 비교 |
| keyword_view | non_brand(브랜드명이 들어가지 않은 검색어), brand_only(브랜드명이 들어간 검색어), all(모든 검색어) | non_brand | 성과 요약 · 검색어별 결과 · 인용 출처 |
| page · page_size | 페이지 번호 1~200 · 페이지당 항목 수 1~200 | 1 · 50 | 브랜드 목록 · 검색어별 결과 · 인용 출처 |
- 측정 데이터는 최근 90일만 보관합니다. 요청한 기간 전체가 보관 기간 밖이면 400 오류(period_out_of_retention)로 거절합니다. 시작일만 보관 기간 밖이면 보관 기간의 첫날부터 조회하고 meta.period.adjusted를 true로 표시합니다.
- 경쟁사 비교는 keyword_view를 받지 않습니다. 브레인드 대시보드의 경쟁 분석과 같이 브랜드명이 들어가지 않은 검색어로만 계산합니다.
- 같은 기간을 짧은 간격으로 반복해 조회하지 말고, 필요한 주기(예: 하루 한 번)에 맞춰 조회해 주세요.
플랫폼 id
| 플랫폼 id | 플랫폼 |
|---|---|
| naver | 네이버 AI 브리핑 |
| google_aio | 구글 AI 개요 |
| google_ai_mode | 구글 AI 모드 |
| gemini | 제미나이 |
| chatgpt | ChatGPT |
| claude | Claude |
플랫폼 이름은 바뀔 수 있으므로, 프로그램에서는 플랫폼 id로 구분해 주세요. 조직의 요금제와 설정에 따라 측정하지 않는 플랫폼도 있습니다.
데이터 API 응답 형식
정상 응답은 HTTP 200과 함께 다음 형식의 JSON을 보냅니다. data에는 조회 결과가, meta에는 조회 조건이 들어갑니다.
{
"api_version": "v1",
"data": { … },
"meta": {
"brand_id": "3f1c…",
"period": { "start": "2026-10-11", "end": "2026-11-09", "days": 30, "adjusted": false },
"platform": null,
"keyword_view": "non_brand",
"page": null,
"page_size": null,
"total": null,
"has_more": null,
"truncated": false,
"generated_at": "2026-11-09T18:30:05+09:00"
}
}측정할 수 없는 값은 null
측정할 수 없는 값은 0이 아니라 null로 보냅니다. AI 답변이 0건이거나 자사 채널을 등록하지 않아 계산할 수 없는 경우입니다. null을 0으로 바꾸어 합계나 평균을 내면 실제보다 낮은 값이 됩니다. 브레인드 대시보드에서 「—」로 표시하는 값과 같습니다.
숫자 규칙
- 비율은 0~100 사이의 숫자로, 소수점 첫째 자리까지 보냅니다. 12.5는 12.5%입니다.
- 평균 언급 순위는 숫자가 작을수록 앞 순위입니다. 직전 기간 대비 변화(change)가 양수이면 순위 숫자가 커진 것, 곧 순위가 내려간 것입니다.
- 날짜는 한국 시간 기준 YYYY-MM-DD, 시각은 ISO 8601 형식(+09:00)입니다.
meta 필드
meta의 필드 목록은 모든 조회가 같습니다. 그 조회와 관계없는 필드는 null입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| brand_id | 문자열 또는 null | 조회한 브랜드 번호 |
| period | 객체 또는 null | 조회 기간 — start, end, days(양 끝을 포함한 일수), adjusted(보관 기간 때문에 시작일을 당겼으면 true) |
| platform | 문자열 또는 null | 지정한 플랫폼 id |
| keyword_view | 문자열 또는 null | 적용한 검색어 보기 |
| page | 숫자 또는 null | 페이지 번호 |
| page_size | 숫자 또는 null | 페이지당 항목 수 |
| total | 숫자 또는 null | 전체 항목 수 |
| has_more | 불리언 또는 null | true이면 다음 페이지가 있습니다. |
| truncated | 불리언 | true이면 기록이 많아 일부 기록으로 계산한 결과입니다. |
| generated_at | 문자열 | 응답을 만든 시각(ISO 8601 · +09:00) |
여러 페이지로 나뉜 결과
브랜드 목록, 검색어별 결과, 인용 출처는 결과를 여러 페이지로 나누어 보냅니다. meta.has_more가 true이면 다음 페이지가 있으므로, page를 1씩 늘려 has_more가 false가 될 때까지 요청합니다. 브랜드 목록은 브랜드 이름순, 검색어별 결과는 검색어 가나다순, 인용 출처는 인용 수가 많은 순입니다.
직전 기간 비교
브랜드 성과 요약의 comparison은 조회 기간과 같은 길이의 직전 기간과 비교한 값입니다. status가 ok일 때만 previous · current · change에 숫자가 들어가고, 그 밖에는 null입니다. 브레인드 대시보드도 이 경우에는 변화를 표시하지 않습니다.
| status | 설명 |
|---|---|
| ok | 비교할 수 있습니다. previous · current · change에 숫자가 들어갑니다. |
| no_previous_data | 직전 기간에 비교할 측정 데이터가 없습니다. |
| outside_retention | 직전 기간의 일부가 보관 기간(최근 90일) 밖에 있어 비교하지 않습니다. |
| low_sample | 어느 한 기간의 AI 답변 수가 적어 비교하지 않습니다. |
| platform_mix | 두 기간의 측정 플랫폼 구성이 달라 비교하지 않습니다. |
| unavailable | 비교 결과를 계산하지 못했습니다. |
데이터 API 조회별 응답 필드
아래 표의 필드는 모두 data 아래에 있습니다. 「[]」는 배열의 각 항목을 뜻합니다.
브랜드 목록 — /api/v1/brands
| 필드 | 타입 | 설명 |
|---|---|---|
| brands[].brand_id | 문자열 | 브랜드 번호. 브랜드별 엔드포인트의 {brand_id}에 사용합니다. |
| brands[].name | 문자열 | 브랜드 이름 |
| brands[].platforms[].id | 문자열 | 측정 중인 플랫폼 id |
| brands[].platforms[].name | 문자열 | 측정 중인 플랫폼 이름 |
| brands[].keyword_count | 숫자 | 등록한 검색어 수 |
| brands[].competitors[] | 문자열 배열 | 등록한 경쟁사 이름 |
브랜드 성과 요약 — /api/v1/brands/{brand_id}/summary
| 필드 | 타입 | 설명 |
|---|---|---|
| brand.brand_id | 문자열 | 브랜드 번호 |
| brand.name | 문자열 | 브랜드 이름 |
| previous_period.start | 문자열 | 비교한 직전 기간의 첫날 |
| previous_period.end | 문자열 | 비교한 직전 기간의 마지막 날 |
| own_channels_registered | 불리언 | 자사 채널 등록 여부. false이면 자사 채널 출처 인용률은 항상 null입니다. |
| overall | 지표 객체 | 전체 플랫폼의 지표. platform을 지정하면 그 플랫폼의 지표입니다. |
| platforms[] | 지표 객체 배열 | 플랫폼별 지표. 지표 객체에 id(플랫폼 id), name(플랫폼 이름), keyword_changes가 더해집니다. |
| platforms[].keyword_changes | 객체 또는 null | 두 기간에 모두 AI 답변이 있는 검색어 수(keywords)와 그중 브랜드 언급률이 내려간 검색어 수(down), 오른 검색어 수(up). 비교할 수 없으면 null입니다. |
| keyword_changes_partial | 불리언 | true이면 기록이 많아 keyword_changes를 일부 기록으로 계산했습니다. |
| weekly_mention_rate[].start | 문자열 | 주의 첫날. 기간 첫날부터 7일씩 묶습니다. |
| weekly_mention_rate[].end | 문자열 | 주의 마지막 날 |
| weekly_mention_rate[].platforms[].id | 문자열 | 플랫폼 id |
| weekly_mention_rate[].platforms[].mention_rate | 숫자 또는 null | 그 주의 브랜드 언급률(%). 일별 값을 AI 답변 수로 가중 평균하므로 기간 값과 조금 다를 수 있습니다. |
| measurement | 객체 또는 null | 기간 안에서 AI 답변을 수집한 날 수(days), 첫날(first_date), 마지막 날(last_date). 수집한 날이 없으면 null입니다. |
overall과 platforms[]에 들어가는 지표 객체는 다음과 같습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| answers | 숫자 | 분석한 AI 답변 수 |
| mention_rate | 숫자 또는 null | 브랜드 언급률(%) |
| first_recommendation_rate | 숫자 또는 null | 첫 추천률(%) |
| avg_rank | 숫자 또는 null | 평균 언급 순위 |
| own_citation_rate | 숫자 또는 null | 자사 채널 출처 인용률(%). 자사 채널을 등록하지 않았으면 null입니다. |
| comparison.status | 문자열 | 직전 기간 비교 상태(아래 「직전 기간 비교」 표) |
| comparison.same_keywords | 불리언 | true이면 두 기간에 모두 AI 답변이 있는 같은 검색어끼리 다시 계산한 비교입니다. 이때 current는 위 기간 값과 다를 수 있습니다. |
| comparison.low_confidence | 불리언 | true이면 어느 한 기간의 AI 답변 수가 적어 참고용으로만 보아야 하는 비교입니다. |
| comparison.{지표}.previous | 숫자 또는 null | 직전 기간 값. {지표} = mention_rate · first_recommendation_rate · own_citation_rate · avg_rank |
| comparison.{지표}.current | 숫자 또는 null | 이번 기간 값 |
| comparison.{지표}.change | 숫자 또는 null | 이번 기간 값 − 직전 기간 값. 비율은 %p, 평균 언급 순위는 순위 차이입니다. |
검색어별 결과 — /api/v1/brands/{brand_id}/keywords
| 필드 | 타입 | 설명 |
|---|---|---|
| keywords[].keyword | 문자열 | 검색어 |
| keywords[].brand_query | 불리언 | 브랜드명이 들어간 검색어 여부 |
| keywords[].platforms[].id | 문자열 | 플랫폼 id. AI 답변이 있는 플랫폼만 들어갑니다. |
| keywords[].platforms[].answers | 숫자 | 분석한 AI 답변 수 |
| keywords[].platforms[].mention_rate | 숫자 또는 null | 브랜드 언급률(%) |
| keywords[].platforms[].own_citation_rate | 숫자 또는 null | 자사 채널 출처 인용률(%) |
| keywords[].platforms[].avg_rank | 숫자 또는 null | 평균 언급 순위 |
| keywords[].platforms[].sentiment | 객체 또는 null | 자사가 언급된 AI 답변의 감성별 답변 수(positive 긍정 · neutral 중립 · negative 부정). 감성을 분석한 답변이 없으면 null입니다. |
AI 답변 인용 출처 — /api/v1/brands/{brand_id}/sources
| 필드 | 타입 | 설명 |
|---|---|---|
| totals.answers | 숫자 | 분석한 AI 답변 수 |
| totals.citations | 숫자 | AI 답변이 인용한 출처의 전체 인용 수 |
| totals.own_citations | 숫자 또는 null | 자사 채널 인용 수. 자사 채널을 등록하지 않았으면 null입니다. |
| totals.own_citation_share | 숫자 또는 null | 전체 인용 중 자사 채널 인용의 비중(%) |
| totals.own_channels_registered | 불리언 | 자사 채널 등록 여부 |
| totals.sources | 숫자 | 인용된 출처 수 |
| sources[].name | 문자열 | 출처 이름(웹사이트 도메인 또는 채널 이름) |
| sources[].type | 문자열 | 출처 종류 id(아래 「출처 종류」 표) |
| sources[].type_name | 문자열 | 출처 종류 이름. 바뀔 수 있으므로 프로그램에서는 type으로 구분합니다. |
| sources[].own | 불리언 | 등록한 자사 채널 여부 |
| sources[].competitor | 문자열 또는 null | 등록한 경쟁사의 채널이면 그 경쟁사 이름 |
| sources[].citations | 숫자 | 인용 수 |
| sources[].keyword_count | 숫자 | 이 출처를 인용한 AI 답변의 검색어 수 |
| sources[].platforms[].id | 문자열 | 플랫폼 id |
| sources[].platforms[].citations | 숫자 | 그 플랫폼의 인용 수 |
| sources[].sample_urls[] | 문자열 배열 | 인용된 웹페이지 주소 예시(최대 3개) |
| 출처 종류 id | 출처 종류 |
|---|---|
| naver_blog | 네이버 블로그 |
| naver_cafe | 네이버 카페 |
| naver_post | 네이버 포스트 |
| brunch | 브런치 |
| youtube | 유튜브 |
| 인스타그램 | |
| X (트위터) | |
| web | 일반 웹 |
경쟁사 비교 — /api/v1/brands/{brand_id}/competitors
| 필드 | 타입 | 설명 |
|---|---|---|
| competitors_registered | 불리언 | 경쟁사 등록 여부. false이면 brands와 platforms가 빈 배열입니다. |
| brands[].name | 문자열 | 브랜드 이름 |
| brands[].own | 불리언 | 자사 여부 |
| brands[].mention_rate | 숫자 또는 null | 브랜드 언급률(%) |
| brands[].mention_rate_rank | 숫자 또는 null | 이 표의 브랜드 중 브랜드 언급률 순위(1 = 가장 높음) |
| brands[].mention_rate_rank_tied | 불리언 | 브랜드 언급률이 같아 같은 순위인 브랜드가 있는지 여부 |
| brands[].avg_rank | 숫자 또는 null | 평균 언급 순위 |
| brands[].channel_citation_rate | 숫자 또는 null | 출처 인용률(%) — 그 브랜드의 채널로 등록한 출처가 AI 답변에 인용된 비율. 등록한 채널이 없으면 null입니다. |
| brands[].mentioned_answers | 숫자 | 그 브랜드가 언급된 AI 답변 수 |
| brands[].answers | 숫자 | 분석한 AI 답변 수 |
| brands[].share | 숫자 또는 null | 브랜드 언급 점유율(%) |
| platforms[].id | 문자열 | 플랫폼 id. platform을 지정하면 platforms는 빈 배열입니다. |
| platforms[].name | 문자열 | 플랫폼 이름 |
| platforms[].brands[].name | 문자열 | 브랜드 이름 |
| platforms[].brands[].mention_rate | 숫자 또는 null | 그 플랫폼의 브랜드 언급률(%) |
| other_brands_share | 숫자 또는 null | 등록하지 않은 다른 브랜드들의 브랜드 언급 점유율 합(%) |
호출 사용량 — /api/v1/usage
| 필드 | 타입 | 설명 |
|---|---|---|
| window_hours | 숫자 | 집계 구간(최근 24시간) |
| key.used | 숫자 | 이 API 키의 최근 24시간 호출 수 |
| key.limit | 숫자 | 이 API 키의 최근 24시간 한도 |
| organization.used | 숫자 | 조직 전체의 최근 24시간 호출 수 |
| organization.limit | 숫자 | 조직 전체의 최근 24시간 한도 |
| key_per_minute_limit | 숫자 | API 키당 1분 한도 |
| key_concurrent_limit | 숫자 | API 키당 동시 처리 한도 |
데이터 API 오류 코드
오류 응답은 HTTP 상태 코드와 함께 다음 형식의 JSON을 보냅니다. code는 바뀌지 않는 영문 식별자이고, message는 한국어 안내 문장입니다. message는 더 알기 쉽게 바뀔 수 있으므로, 프로그램에서는 code로 구분해 주세요.
{
"error": {
"code": "rate_limited",
"message": "호출 한도를 넘었습니다. …"
}
}| code | HTTP 상태 | 설명 |
|---|---|---|
| invalid_parameter | 400 | 입력값 형식이 맞지 않습니다. 같은 파라미터를 두 번 보냈거나 값이 너무 깁니다. |
| unknown_parameter | 400 | 이 조회가 받지 않는 파라미터가 있습니다. |
| invalid_period | 400 | 날짜 형식이 맞지 않거나 start가 end보다 늦습니다. |
| period_too_long | 400 | 조회 기간이 90일을 넘습니다. |
| period_out_of_retention | 400 | 요청한 기간 전체가 보관 기간(최근 90일) 밖에 있습니다. |
| invalid_platform | 400 | platform 값이 플랫폼 id가 아닙니다. |
| invalid_keyword_view | 400 | keyword_view 값이 맞지 않습니다. |
| invalid_page | 400 | page 또는 page_size가 범위(1~200 · 1~200)를 벗어났습니다. |
| key_in_url | 400 | URL에 API 키가 들어 있습니다. 그 키는 폐기하고 새로 발급해 주세요. |
| invalid_authorization | 400 | Authorization 헤더가 두 개 이상입니다. |
| unauthorized | 401 | API 키가 없거나, 틀렸거나, 폐기·만료되었습니다(네 경우 모두 같은 응답). |
| browser_request_blocked | 403 | 웹 브라우저에서 보낸 요청입니다. |
| organization_unavailable | 403 | 조직이 지금 데이터를 조회할 수 없는 상태입니다. |
| plan_not_included | 403 | 조직의 요금제에 데이터 API가 포함되어 있지 않습니다. |
| not_found | 404 | brand_id가 없거나 이 API 키로 조회할 수 없는 브랜드입니다. |
| method_not_allowed | 405 | GET 이외의 요청입니다. |
| response_too_large | 413 | 응답이 2MB를 넘습니다. page_size를 줄여 다시 요청해 주세요. |
| rate_limited | 429 | 호출 한도를 넘었습니다. Retry-After 헤더의 시간(초)이 지난 뒤 다시 요청해 주세요. |
| internal_error | 500 | 요청을 처리하지 못했습니다. |
| service_unavailable | 503 | 분석 결과를 불러오지 못했습니다. |
| upstream_timeout | 504 | 분석 결과를 계산하는 시간이 너무 오래 걸렸습니다. 기간을 줄이거나 잠시 후 다시 요청해 주세요. |
- 401 오류는 API 키가 없거나 틀린 경우와 폐기되었거나 만료된 경우를 구분하지 않고 같은 응답을 보냅니다. 「조직 설정 → API 키」 목록에서 그 키의 만료일을 확인해 주세요.
- 404 오류는 brand_id가 없는 경우와 이 API 키로 조회할 수 없는 브랜드인 경우를 구분하지 않습니다.
- 429 · 500 · 503 · 504 오류는 잠시 후 다시 요청하면 처리될 수 있습니다. 같은 요청을 바로 반복하지 말고 간격을 늘려 가며 다시 요청해 주세요.
데이터 API 호출 한도
| 구분 | 한도 |
|---|---|
| API 키당 1분 | 60회 |
| API 키당 최근 24시간 | 2,000회 |
| 조직 전체 최근 24시간 | 5,000회 |
| API 키당 동시 처리 | 3건 |
- 한도를 넘으면 429 오류와 함께 다시 요청할 수 있을 때까지 남은 시간(초)을 Retry-After 헤더로 보냅니다.
- 최근 24시간 한도는 요청한 시각부터 거슬러 24시간 동안의 호출 수를 집계합니다. 날짜가 바뀌어도 초기화되지 않습니다.
- 호출 사용량 조회(/api/v1/usage), 429 응답, API 키·조직·요금제 확인 단계에서 거절된 요청(401, 403, URL에 API 키를 넣은 400 등)은 호출 수에 포함하지 않습니다. 이 확인을 통과한 뒤의 입력 오류(400)와 404 오류는 호출 수에 포함합니다.
API 키 교체와 폐기
정기 교체
- 「조직 설정 → API 키」 목록에서 기존 키의 「같은 설정으로 새 키」를 선택해, 같은 이름·브랜드·유효 기간으로 새 키를 발급합니다.
- 키를 사용하는 프로그램에 새 키를 적용합니다.
- 새 키로 데이터를 조회하는지 확인한 뒤 기존 키를 폐기합니다.
API 키는 만료일이 지나면 동작하지 않습니다. 만료 14일 전에 조직의 소유자·관리자와 키를 발급한 구성원에게 안내 메일을 보냅니다.
키가 노출된 경우
- 「조직 설정 → API 키」 목록에서 그 키의 마지막 사용 시각과 IP 주소를 확인해 기록해 둡니다. 폐기한 키는 목록에서 사라집니다.
- 그 키를 폐기합니다. 폐기한 키는 다음 요청부터 401 오류로 거절합니다.
- 새 키를 발급해 프로그램에 적용합니다.
- 폐기해도 그 키로 이미 조회한 데이터는 회수되지 않습니다.
- 조직의 모든 키를 한꺼번에 폐기하려면 목록 아래 「모든 키 폐기」를 선택합니다.
- 새 API 키를 발급하면 조직의 소유자·관리자 모두에게 알림 메일을 보냅니다. 발급 사실을 알지 못한다면 그 키를 폐기해 주세요.
요금제와 조직 상태에 따른 동작
- 요금제를 데이터 API가 포함되지 않은 요금제로 바꾸면 조회는 403 오류(plan_not_included)로 거절하고 새 키는 발급할 수 없습니다. 기존 키는 폐기하지 않으므로, 다시 Business 이상 요금제로 바꾸면 만료 전인 키로 조회할 수 있습니다.
- 조직을 삭제하면 그 조직의 모든 API 키를 폐기합니다. 조직을 복원해도 폐기한 키는 동작하지 않으므로 새로 발급해야 합니다.
- 브랜드를 삭제하거나 비활성화하면 그 브랜드는 조회할 수 없으며 404 오류로 거절합니다.
데이터 API 호출 예시
Python
requests 라이브러리로 검색어별 결과를 마지막 페이지까지 조회하는 예시입니다.
import os
import requests
API = "https://braind.pro/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BRAIND_API_KEY']}"}
brand_id = "브랜드 목록에서 확인한 brand_id"
rows, page = [], 1
while True:
r = requests.get(
f"{API}/brands/{brand_id}/keywords",
headers=HEADERS,
params={"start": "2026-10-01", "end": "2026-10-31", "page": page, "page_size": 200},
timeout=60,
)
r.raise_for_status()
body = r.json()
rows += body["data"]["keywords"]
if not body["meta"]["has_more"]:
break
page += 1엑셀 파워 쿼리
엑셀의 「데이터 → 데이터 가져오기 → 기타 원본에서 → 빈 쿼리」를 연 뒤, 고급 편집기에 다음 내용을 붙여 넣는 예시입니다. 처음 실행할 때 웹 콘텐츠에 접근하는 방법을 묻는 창이 나오면 「익명」을 선택합니다.
let
ApiKey = "발급한 API 키",
Source = Json.Document(
Web.Contents(
"https://braind.pro/api/v1/brands",
[Headers = [Authorization = "Bearer " & ApiKey]]
)
),
Brands = Table.FromRecords(Source[data][brands])
in
Brands통합 문서를 다른 사람과 공유하면 쿼리에 입력한 API 키도 함께 전달됩니다. 통합 문서를 공유하기 전에 쿼리에서 API 키를 지워 주세요.
데이터 API 변경 기록
- v1의 필드 이름과 타입은 바꾸지 않습니다. 새 필드는 추가할 수 있으므로, 프로그램은 모르는 필드를 무시하도록 작성해 주세요.
- 필드 이름이나 타입을 바꿔야 하면 v2 엔드포인트를 새로 제공하고, v1을 90일 이상 함께 운영합니다.
- 지표 계산 방식이 바뀌면 필드는 그대로 두고 값이 달라집니다. 이 경우 아래 표에 날짜와 내용을 적습니다.
| 날짜 | 변경 내용 |
|---|---|
| 2026-11-09 | 데이터 API v1 공개 |