조회 - 네이버 검색광고

이 쪽의 모든 작업에 해당

이 작업은 샌드박스를 지원하지 않습니다. 샌드박스로 보내면 거절되므로 데모나 정식 환경으로 호출합니다.

1. 네이버 검색광고 광고그룹 목록 조회naver_searchad.adgroups.read

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

고른 캠페인 아래의 광고그룹 목록을 받아 옵니다. 캠페인 식별자 하나를 넣으며 조회만 합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.adgroups.read`이 API 고정값 (기본값) 예시 : naver_searchad.adgroups.read
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
nccCampaignId	string	Y	광고그룹을 조회할 캠페인 ID 입니다. 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값은 바꾸지 않고 그대로 보냅니다
baseSearchId	string	N	광고그룹 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
recordSize	string	N	광고그룹 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다. 네이버 문서의 상한이 언어판마다 달라(한국어 1000, 영어 2000) 이 서비스는 상한을 검사하지 않습니다
selector	string	N	광고그룹 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.adgroups.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "nccCampaignId": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 광고그룹 식별자, 광고그룹 이름, 운영 상태

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.adgroups.read",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

2. 네이버 검색광고 광고 소재 목록 조회naver_searchad.ads.read

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

고른 광고그룹에 걸린 광고 소재 목록을 받아 옵니다. 광고그룹 식별자를 넣으며 조회만 합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.ads.read`이 API 고정값 (기본값) 예시 : naver_searchad.ads.read
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	nccAdgroupId	string	조건부	광고를 조회할 광고그룹 ID 입니다. nccAdgroupId 와 ids 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값은 바꾸지 않고 그대로 보냅니다
	ids	string	조건부	네이버 검색광고 API 의 ids 조회 조건입니다. nccAdgroupId 와 ids 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.ads.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "nccAdgroupId": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 소재 식별자, 소재 내용, 운영 상태

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.ads.read",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

3. 네이버 검색광고 비즈머니 잔액 조회naver_searchad.bizmoney.read

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

광고비로 쓰는 비즈머니 잔액과 잠금 여부를 확인합니다. 넣을 값은 없으며 조회만 합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.bizmoney.read`이 API 고정값 (기본값) 예시 : naver_searchad.bizmoney.read
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.bizmoney.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 비즈머니 잔액, 예산 잠금 여부, 환불 잠금 여부

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.bizmoney.read",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

4. 네이버 검색광고 캠페인 목록 조회naver_searchad.campaigns.read

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

연동한 네이버 검색광고 계정의 캠페인 목록을 한 번에 받아 옵니다. 조회만 하며 광고 설정을 바꾸지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.campaigns.read`이 API 고정값 (기본값) 예시 : naver_searchad.campaigns.read
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
campaignType	string	N	캠페인 목록 조회의 선택 조건입니다(조건 없이 부르면 계정 전체 캠페인을 조회합니다). 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
baseSearchId	string	N	캠페인 목록 조회의 선택 조건입니다(조건 없이 부르면 계정 전체 캠페인을 조회합니다). 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
recordSize	string	N	캠페인 목록 조회의 선택 조건입니다(조건 없이 부르면 계정 전체 캠페인을 조회합니다). 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다. 네이버 문서의 상한이 언어판마다 달라(한국어 1000, 영어 2000) 이 서비스는 상한을 검사하지 않습니다
selector	string	N	캠페인 목록 조회의 선택 조건입니다(조건 없이 부르면 계정 전체 캠페인을 조회합니다). 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.campaigns.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 캠페인 식별자, 캠페인 이름, 운영 상태

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.campaigns.read",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

5. 네이버 검색광고 키워드 목록 조회naver_searchad.keywords.read

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

고른 광고그룹에 등록한 키워드 목록을 받아 옵니다. 키워드 추천이 아니라 이미 등록한 키워드이며 조회만 합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.keywords.read`이 API 고정값 (기본값) 예시 : naver_searchad.keywords.read
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
nccAdgroupId	string	Y	키워드를 조회할 광고그룹 ID 입니다. 그 광고그룹에 등록된 키워드를 조회하며 키워드 도구의 결과가 아닙니다. 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다
baseSearchId	string	N	키워드 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
recordSize	string	N	키워드 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다. 네이버 문서의 상한이 언어판마다 달라(한국어 1000, 영어 2000) 이 서비스는 상한을 검사하지 않습니다
selector	string	N	키워드 목록 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.keywords.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "nccAdgroupId": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 키워드 식별자, 키워드, 입찰가, 운영 상태

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.keywords.read",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

6. 네이버 검색광고 성과 보고서 조회naver_searchad.performance.report

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

캠페인이나 광고그룹의 노출, 클릭, 비용 같은 성과를 기간을 정해 받아 옵니다. 보고 싶은 지표를 골라 넣으며 조회만 합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `naver_searchad`이 API 고정값 (기본값) 예시 : naver_searchad
action	string	-	Y	호출할 작업입니다. `naver_searchad.performance.report`이 API 고정값 (기본값) 예시 : naver_searchad.performance.report
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
fields	array	Y	성과 보고서에 받을 항목 이름의 JSON 배열입니다(예: ["impCnt", "clkCnt", "salesAmt"]). 배열로 보내면 JSON 문자열로 바꿔 보내고 이미 JSON 문자열이면 그대로 보내며, 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다
id	string	조건부	성과를 조회할 대상 ID 입니다. id 와 ids 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값은 바꾸지 않고 그대로 보냅니다
ids	string	조건부	네이버 검색광고 API 의 ids 조회 조건입니다. id 와 ids 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
timeRange	object	조건부	조회 기간입니다. timeRange 와 datePreset 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 객체로 보내면 JSON 문자열로 바꿔 보내고 문자열이면 그대로 보내며, 허용 형식은 네이버 검색광고 API 를 따릅니다
datePreset	string	조건부	조회 기간을 정하는 조건으로 timeRange 대신 쓸 수 있습니다(예: last7days, last30days). timeRange 와 datePreset 중 하나는 반드시 보내야 하며, 둘 다 비어 있으면 네이버에 요청하지 않고 필요한 값이라고 답합니다. 값은 바꾸지 않고 그대로 보내므로 허용 값은 네이버 검색광고 API 를 따릅니다
timeIncrement	string	N	성과 보고서 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다
breakdown	string	N	성과 보고서 조회의 선택 조건입니다. 값의 형식은 검사하지 않고 네이버 검색광고 API 에 같은 이름의 조회 조건으로 그대로 보내므로, 허용 값과 형식은 네이버 검색광고 API 를 따릅니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "naver_searchad",
  "action": "naver_searchad.performance.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "fields": "<필수: array>",
    "id": "<필수>",
    "datePreset": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 노출 수, 클릭 수, 광고비, 기간 합계

순번	변수명	설명
	result	네이버 검색광고 API 가 돌려준 응답 본문을 가공하지 않고 그대로 담습니다. 안쪽 칸의 이름과 값은 네이버가 정하므로 이 문서가 보장하지 않고, 칸의 뜻은 네이버 검색광고 API 문서를 따릅니다. 객체의 키 순서는 보존되지 않을 수 있습니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "naver_searchad",
    "action": "naver_searchad.performance.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}