메타 크리에이터 마켓플레이스 검색 (ADMIN 전용, 커서 페이지네이션)

크리에이터 마켓플레이스 검색 (ADMIN)

필터로 메타에 온보딩된 크리에이터를 검색합니다. 페이지당 10건 하드캡 + 커서 페이지네이션. 인사이트(insights)는 인라인으로 함께 반환됩니다.

표준 액세스에서는 mock 데이터(mocked_username_*)가 내려오며 응답 mock=true 입니다. App Review 승인 후 동일 필드로 실데이터가 자동 전환됩니다. 자세한 배경은 개요 참고.

HTTP 요청

GET /ai/admin/meta-creator-marketplace/creators
Authorization: Bearer {admin_access_token}

쿼리 파라미터

모두 선택값입니다. 형식이 잘못되면 메타가 silent ignore 하므로 서버가 형식(shape) 을 검증해 400 으로 막습니다(비즈니스 자격 규칙은 강제하지 않음).

파라미터	타입	예시	설명
`country`	`String`	`KR`	ISO 2자리 국가코드. 콤마로 다중(`KR,JP`). → `creator_countries=["KR"]`
`minFollowers`	`Long`	`10000`	팔로워 하한(숫자, "10K" 아님). `min < max` 강제
`maxFollowers`	`Long`	`100000`	팔로워 상한(숫자)
`interests`	`String`	`BEAUTY`	관심사 enum(UPPER_SNAKE). 콤마로 다중. → `creator_interests=["BEAUTY"]`
`gender`	`String`	`FEMALE`	성별 enum
`ageBucket`	`String`	`18_to_24`	연령 구간 (`{nn}_to_{nn}` 또는 `{nn}_plus`)
`recommendationType`	`String`	`high_ad_performance`	추천 유형 (lower_snake)
`reelsInteractionRate`	`String`	`over_3_percent`	릴스 응답률 구간 (lower_snake)
`query`	`String`	`makeup`	키워드 검색
`cursor`	`String`	—	다음 페이지 커서. 직전 응답의 `nextCursor` 를 그대로 전달

응답

성공 응답 (200 OK) — 표준(mock)

{
  "status": 200,
  "code": null,
  "message": "크리에이터 조회 완료",
  "data": {
    "data": [
      {
        "id": "",
        "username": "mocked_username_1",
        "biography": "proceed through app review",
        "country": "KR",
        "gender": "FEMALE",
        "isAccountVerified": false,
        "ageBucket": "18_to_24",
        "profilePictureUrl": "https://...",
        "onboardedStatus": "ONBOARDED",
        "hasBrandPartnershipExperience": true,
        "pastBrandPartnershipPartners": [],
        "insights": {
          "total_followers": 22998,
          "creator_engaged_accounts": 1234,
          "creator_reach": 56789,
          "reels_hook_rate": 0.12,
          "reels_interaction_rate": 0.034
        }
      }
    ],
    "nextCursor": "QVFIU...",
    "usagePercent": 7,
    "mock": true
  }
}

응답 필드

data 는 { data: 크리에이터[], nextCursor, usagePercent, mock } 구조입니다.

필드	타입	설명
`data[]`	`Array`	이번 페이지 크리에이터 목록 (최대 10)
`nextCursor`	`String`	다음 페이지 커서. 더 없으면 `null`
`usagePercent`	`Integer`	이번 호출의 `creator_marketplace` 레이트리밋 사용률(%). 헤더 없으면 `null`
`mock`	`Boolean`	mock 데이터 여부(표준 액세스 `true`)

크리에이터 (`data[]`) 필드

필드	타입	설명
`id`	`String`	크리에이터 IG 사용자 ID (mock 은 빈 값)
`username`	`String`	IG 사용자명
`biography`	`String`	소개
`country`	`String`	ISO 국가코드
`gender`	`String`	성별
`isAccountVerified`	`Boolean`	인증 계정 여부
`ageBucket`	`String`	연령 구간 (예: `18_to_24`)
`profilePictureUrl`	`String`	프로필 사진 URL
`onboardedStatus`	`String`	마켓플레이스 온보딩 상태
`hasBrandPartnershipExperience`	`Boolean`	브랜드 협업 경험 여부
`pastBrandPartnershipPartners`	`Array/Object`	과거 협업 파트너 (구조 유동적, 통과)
`insights`	`Object`	인사이트 묶음 (아래) — 메타 응답 구조를 그대로 통과
`recentMedia`	`Object`	최근 미디어 (mock 은 빈 id)

`insights` 메트릭

메트릭	의미	기간
`total_followers`	총 팔로워	lifetime
`creator_engaged_accounts`	참여 계정 수	this_month
`creator_reach`	도달	this_month
`reels_hook_rate`	릴스 후크 비율	last_90d
`reels_interaction_rate`	릴스 응답률	last_90d

breakdown(연령/성별/팔로우유형/미디어유형/국가/도시)은 메트릭마다 지원 조합이 달라(engaged_accounts=AGE/GENDER, reach=FOLLOW_TYPE/MEDIA_TYPE 등) 후속 단계에서 실측 후 인라인 확장 예정입니다. insights 는 메타 응답을 통째로 통과시키므로, 확장 시 응답에 자동 포함됩니다.

페이지네이션

# 1페이지
GET /ai/admin/meta-creator-marketplace/creators?country=KR&minFollowers=10000&maxFollowers=100000

# 2페이지 (1페이지 응답의 nextCursor 사용)
GET /ai/admin/meta-creator-marketplace/creators?country=KR&minFollowers=10000&maxFollowers=100000&cursor=QVFIU...

권한

ADMIN 전용. 일반 기업 회원은 호출 불가 (403).

에러 응답

상태 코드	code	설명
`400`	`BAD_REQUEST`	필터 형식 위반 (국가코드/팔로워 범위/enum 형식 등)
`403`	`FORBIDDEN`	관리자 권한 없음
`502`	`META_UPSTREAM_ERROR`	설정 누락 / 페이지토큰 추출 실패(유저토큰 만료 등) / 메타 호출 실패

GET /ai/admin/meta-creator-marketplace/creators