계정

사용량 인사이트 조회

/insights 페이지에 필요한 모든 데이터를 한 번의 왕복으로 반환합니다: 3개 지표(토큰/지출/요청 수)의 추세, 지표별 상위 3개 모델, 프롬프트 캐시 적중 통계, 토큰 분석, 연간 히트맵(스트릭 포함), 크레딧/무료 모델 사용량, 필터 패널 옵션. (사용자, period, heatmap_metric, 필터) 조합별로 5분간 캐시됩니다.

GET/api/v1/insights

인증

Authorization필수

string · header

Authorization 헤더에 Bearer 토큰으로 API 키를 전달합니다.

쿼리 파라미터

period

string

페이지 전체의 시간 범위를 결정하며 기본값은 7d입니다. 인식할 수 없는 값은 400을 반환합니다.

7d30dytdall

Example: "30d"

heatmap_metric

string

연간 히트맵이 표시할 지표(히트맵은 period와 무관하게 항상 전체 달력 연도), 기본값은 spend입니다. 인식할 수 없는 값은 400을 반환합니다.

spendtokensrequests

Example: "tokens"

model

string

페이지 전역 필터 — 이 모델의 사용량만 집계합니다. 생략하면 필터가 적용되지 않습니다.

api_key_id

string

페이지 전역 필터 — 이 API 키의 사용량만 집계합니다. 생략하면 필터가 적용되지 않습니다.

app

string

페이지 전역 필터 — 이 앱 이름(x-title / HTTP-Referer)으로 태그된 사용량만 집계합니다. 생략하면 필터가 적용되지 않습니다.

GET /api/v1/insights

1
2
curl "https://bazaarlink.ai/api/v1/insights?period=30d&heatmap_metric=tokens" \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY"

응답 예시

성공. trend/topModels/heatmap은 항상 3개 지표(tokens, spend, requests) 모두의 전체 데이터를 반환하므로 프런트엔드 토글 시 재요청이 필요 없습니다. caching과 breakdown은 period에 따라 버킷화됩니다(120일 이하는 일 단위, 730일 이하는 주 단위, 그 외는 월 단위). 아래 예시는 축약된 것이며 실제 buckets/heatmap.days 배열은 period 길이에 따라 다수의 항목을 포함합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
{
  "period": "30d",
  "bucketUnit": "day",
  "trend": {
    "tokens": {
      "total": 152000,
      "prevTotal": 98000,
      "changePct": 55.1,
      "buckets": [
        {
          "date": "2026-07-01",
          "segs": [
            {
              "model": "openai/gpt-4.1",
              "value": 5200
            }
          ]
        }
      ]
    },
    "spend": {
      "total": 4.82,
      "prevTotal": 3.1,
      "changePct": 55.5,
      "buckets": [
        {
          "date": "2026-07-01",
          "segs": [
            {
              "model": "openai/gpt-4.1",
              "value": 0.16
            }
          ]
        }
      ]
    },
    "requests": {
      "total": 340,
      "prevTotal": 210,
      "changePct": 61.9,
      "buckets": [
        {
          "date": "2026-07-01",
          "segs": [
            {
              "model": "openai/gpt-4.1",
              "value": 12
            }
          ]
        }
      ]
    }
  },
  "topModels": {
    "tokens": [
      {
        "model": "openai/gpt-4.1",
        "provider": "openai",
        "value": 152000,
        "unit": "tokens"
      }
    ],
    "spend": [
      {
        "model": "openai/gpt-4.1",
        "provider": "openai",
        "value": 4.82,
        "unit": "spend"
      }
    ],
    "requests": [
      {
        "model": "openai/gpt-4.1",
        "provider": "openai",
        "value": 340,
        "unit": "requests"
      }
    ]
  },
  "caching": {
    "buckets": [
      {
        "date": "2026-07-01",
        "hit": 3200,
        "write": 800
      }
    ],
    "totalHit": 96000,
    "totalWrite": 24000
  },
  "breakdown": {
    "buckets": [
      {
        "date": "2026-07-01",
        "prompt": 4000,
        "completion": 1200,
        "reasoning": 0,
        "cached": 3200
      }
    ],
    "totals": {
      "prompt": 120000,
      "completion": 32000,
      "reasoning": 0,
      "cached": 96000
    }
  },
  "heatmap": {
    "spend": {
      "days": [
        {
          "date": "2026-01-01",
          "value": 0.02
        }
      ],
      "streak": {
        "current": 5,
        "longest": 21
      },
      "avgDay": 0.16,
      "avgWeek": 1.12,
      "total": 58.4
    },
    "tokens": {
      "days": [
        {
          "date": "2026-01-01",
          "value": 640
        }
      ],
      "streak": {
        "current": 5,
        "longest": 21
      },
      "avgDay": 5066,
      "avgWeek": 35462,
      "total": 1850000
    },
    "requests": {
      "days": [
        {
          "date": "2026-01-01",
          "value": 4
        }
      ],
      "streak": {
        "current": 5,
        "longest": 21
      },
      "avgDay": 11.3,
      "avgWeek": 79,
      "total": 4130
    }
  },
  "credit": {
    "today": 0.16,
    "thisWeek": 1.12,
    "thisMonth": 4.82
  },
  "freeModel": {
    "today": 0,
    "thisWeek": 0,
    "thisMonth": 0
  },
  "facets": {
    "models": [
      "openai/gpt-4.1"
    ],
    "apiKeys": [
      {
        "id": "key_abc123",
        "name": "default"
      }
    ],
    "apps": [
      "my-app"
    ]
  }
}