Skip to main content
GET
/
v1
/
profiles
프로필 목록 조회
curl --request GET \
  --url https://sajuapi.dev/v1/profiles \
  --header 'X-API-Key: <api-key>'

Documentation Index

Fetch the complete documentation index at: https://docs.sajuapi.dev/llms.txt

Use this file to discover all available pages before exploring further.

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;
}