Skip to main content
GET
https://sajuapi.dev
/
v1
/
fortunes
운세 목록 조회
curl --request GET \
  --url https://sajuapi.dev/v1/fortunes \
  --header 'X-API-Key: <api-key>'
v1 Enterprise API (Coming Soon)이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다. 현재는 v0 API를 사용하세요.
생성된 운세 목록을 조회합니다. 결과는 페이지네이션되어 반환되며, 다양한 필터를 적용할 수 있습니다.

​
Query 파라미터

​
profile_id
string
특정 프로필의 운세만 조회합니다.
​
fortune_type
string
운세 유형으로 필터링합니다. daily, yearly, monthly 중 하나입니다.
​
fortune_date
string
특정 날짜의 운세만 조회합니다. YYYY-MM-DD 형식입니다.
​
date_from
string
지정된 날짜 이후의 운세를 조회합니다. YYYY-MM-DD 형식입니다.
​
date_to
string
지정된 날짜 이전의 운세를 조회합니다. YYYY-MM-DD 형식입니다.
​
model
string
사용된 AI 모델로 필터링합니다.
​
limit
integer
default:"20"
한 페이지에 반환할 운세 수입니다. 1에서 100 사이의 값이어야 합니다.
​
cursor
string
다음 페이지를 조회하기 위한 커서입니다.

​
Response

​
성공

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

​
실패

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

​
요청 예시

curl -X GET "https://api.sajuapi.dev/v1/fortunes?profile_id=prf_abc123&fortune_type=daily&limit=10" \
  -H "X-API-Key: bs_live_xxx"

​
응답 예시

{
  "data": [
    {
      "id": "ftn_xyz789abc123",
      "profile_id": "prf_abc123def456",
      "fortune_type": "daily",
      "fortune_date": "2025-01-16",
      "model": "sonnet",
      "score": 85,
      "summary": "오늘은 새로운 기회가 찾아오는 날입니다.",
      "cached": false,
      "generated_at": "2025-01-16T09:00:00Z"
    },
    {
      "id": "ftn_abc123xyz789",
      "profile_id": "prf_abc123def456",
      "fortune_type": "daily",
      "fortune_date": "2025-01-15",
      "model": "haiku",
      "score": 72,
      "summary": "안정적인 하루가 예상됩니다.",
      "cached": true,
      "generated_at": "2025-01-15T09:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImZ0bl9hYmMxMjN4eXo3ODkifQ==",
  "total_count": 45
}

​
날짜 범위 조회

특정 기간의 운세를 조회할 때 date_from과 date_to를 함께 사용합니다. 
// 최근 7일간의 운세 조회
const today = new Date();
const weekAgo = new Date(today);
weekAgo.setDate(weekAgo.getDate() - 7);

const params = new URLSearchParams({
  profile_id: 'prf_abc123',
  date_from: weekAgo.toISOString().split('T')[0],
  date_to: today.toISOString().split('T')[0]
});

const response = await fetch(`/v1/fortunes?${params}`, {
  headers: { 'X-API-Key': 'bs_live_xxx' }
});