Skip to main content
GET
https://sajuapi.dev
/
v1
/
profiles
프로필 목록 조회
curl --request GET \
  --url https://sajuapi.dev/v1/profiles \
  --header 'X-API-Key: <api-key>'
v1 Enterprise API (Coming Soon)이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다. 현재는 v0 API를 사용하세요.
등록된 프로필 목록을 조회합니다. 결과는 페이지네이션되어 반환되며, 민감한 정보는 마스킹 처리됩니다.

​
Query 파라미터

​
limit
integer
default:"20"
한 페이지에 반환할 프로필 수입니다. 1에서 100 사이의 값이어야 합니다.
​
cursor
string
다음 페이지를 조회하기 위한 커서입니다. 이전 응답의 next_cursor 값을 사용합니다.
​
day_master_element
string
일주 오행으로 필터링합니다. wood, fire, earth, metal, water 중 하나입니다.
​
created_after
string
지정된 시간 이후에 생성된 프로필만 반환합니다. ISO 8601 형식입니다.
​
created_before
string
지정된 시간 이전에 생성된 프로필만 반환합니다. ISO 8601 형식입니다.

​
Response

​
성공

프로필 목록 조회에 성공하면 프로필 배열과 페이지네이션 정보가 반환됩니다.
필드타입설명
dataarrayProfile 객체 배열입니다.
has_moreboolean다음 페이지가 있는지 여부입니다.
next_cursorstring다음 페이지 조회를 위한 커서입니다. has_more가 true일 때만 반환됩니다.
total_countinteger필터 조건에 맞는 전체 프로필 수입니다.

​
실패

상태 코드에러 타입설명
400validation_error쿼리 파라미터가 유효하지 않음
401authentication_errorAPI 키가 유효하지 않음
429rate_limited요청 한도 초과

​
요청 예시

curl -X GET "https://api.sajuapi.dev/v1/profiles?limit=10&day_master_element=fire" \
  -H "X-API-Key: bs_live_xxx"

​
응답 예시

{
  "data": [
    {
      "id": "prf_abc123def456",
      "external_id": "user_12345",
      "name": "김**",
      "birth_year": "19**",
      "gender": "male",
      "day_master": "병화",
      "day_master_element": "fire",
      "weakest_element": "water",
      "created_at": "2025-01-15T09:00:00Z",
      "updated_at": "2025-01-15T09:00:00Z"
    },
    {
      "id": "prf_def456ghi789",
      "external_id": "user_67890",
      "name": "이**",
      "birth_year": "19**",
      "gender": "female",
      "day_master": "정화",
      "day_master_element": "fire",
      "weakest_element": "metal",
      "created_at": "2025-01-14T15:30:00Z",
      "updated_at": "2025-01-14T15:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InByZl9kZWY0NTZnaGk3ODkifQ==",
  "total_count": 1523
}

​
페이지네이션

커서 기반 페이지네이션을 사용하여 대량의 프로필을 효율적으로 조회할 수 있습니다. 
async function getAllProfiles() {
  let cursor = null;
  const allProfiles = [];

  do {
    const url = new URL('https://api.sajuapi.dev/v1/profiles');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: { 'X-API-Key': 'bs_live_xxx' }
    });
    const { data, has_more, next_cursor } = await response.json();

    allProfiles.push(...data);
    cursor = has_more ? next_cursor : null;
  } while (cursor);

  return allProfiles;
}