> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 보낸 데이터 확인하기

> 보낸 이벤트가 저장되고 사용량으로 집계되어 청구 예정액에 반영됐는지 순서대로 확인합니다.

이벤트를 보낸 뒤에는 숫자가 단계마다 이어지는지 확인합니다. 이벤트가 저장됐는지, 미터가 그 이벤트를 사용량으로 셌는지, 사용량에 단가가 붙어 청구 예정액이 나왔는지 차례로 봅니다. 어느 단계에서 숫자가 끊기는지 알면 원인을 빨리 좁힐 수 있습니다.

## 확인하기 전에

콘솔에서 확인한다면 로그인 뒤 화면 위 '업무 환경'이 '테스트 환경'인지 확인하세요. API 키는 발급한 업무 환경에 고정되어 있어서, 테스트 환경 키(me\_test\_)로 보낸 이벤트는 콘솔이 '테스트 환경'일 때만 보입니다. 업무 환경을 바꾸는 방법은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)을 보세요.

API로 확인할 때는 read(조회) 권한이 있는 키가 필요합니다. 이벤트 전송용으로 ingest(수집) 권한만 준 키로는 조회할 수 없습니다. 조회는 read, 고객 등록과 이벤트 전송은 ingest, 그 밖의 변경은 admin 권한이 필요합니다. 자세한 내용은 [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)을 보세요.

## 단계별 화면과 API

| 확인할 것 | 콘솔 화면 | API |
| - | - | - |
| 이벤트가 저장됐는가 | '수집 로그' | `GET /v1/events/lookup`, `GET /v1/events` |
| 사용량으로 집계됐는가 | '사용량' | `GET /v1/usage` |
| 청구 예정액에 들었는가 | '청구 검토' | `GET /v1/invoices/draft` |
| 저장됐지만 청구에 안 잡힌 이벤트 | '이벤트 매핑 진단' | `GET /v1/event-issues/search` |
| 저장되지 못한 요청 | '수집 거절' | `GET /v1/event-rejections/search` |
| 청구에서 빠지거나 확인할 이벤트 건수 | '사용량' 화면의 '수집 확인과 정정' | `GET /v1/unbilled-events` |
| 확정이 끝난 금액 | '확정 인보이스' | `GET /v1/invoices` |

콘솔 화면은 모두 왼쪽 메뉴 '사용량에서 수납까지' 묶음에 있습니다.

## 확인 순서

아래 예시는 테스트 환경 고객 '에이콘랩'에게 `llm_usage` 유형 이벤트를 보냈고, 미터 `tokens`가 `tokens` 속성을 `sum`으로 집계하며 `model` 속성으로 단가를 나누는 경우입니다.

**1. 이벤트가 저장됐는지 본다**

`POST /v1/events`가 200과 `"duplicate": false`를 돌려주면 그 요청으로 이벤트가 저장된 것입니다. `"duplicate": true`면 같은 `transaction_id`의 이벤트가 이미 있었다는 뜻이고, 이번 요청 본문은 저장되지 않았습니다.

저장된 내용은 `transaction_id`로 다시 읽어 확인합니다.

> [tab] API
>
> ```bash curl theme={null}
> curl -sS "https://meterengine.com/v1/events/lookup?transaction_id=req_20261105_0001" \
>   -H "Authorization: Bearer me_test_xxxxxxxx"
> ```
>
> ```javascript Node theme={null}
> const params = new URLSearchParams({ transaction_id: "req_20261105_0001" });
> const response = await fetch(`https://meterengine.com/v1/events/lookup?${params}`, {
>   headers: { Authorization: "Bearer me_test_xxxxxxxx" },
> });
> const event = await response.json();
> ```
>
> ```json 200 응답 theme={null}
> {
>   "transaction_id": "req_20261105_0001",
>   "customer_id": "3f6c2a1e-8b4d-4e2a-9c71-5d0b8e2f4a10",
>   "customer_name": "에이콘랩",
>   "type": "llm_usage",
>   "properties": { "model": "small", "tokens": 1234 },
>   "occurred_at": "2026-11-05T01:00:00Z",
>   "received_at": "2026-11-05T01:00:02.318452Z",
>   "request_id": "7d1c9e04-2b6a-4f0e-8a53-91e4c6b2d7f8",
>   "actor_type": "api_key",
>   "actor_id": "b2e8f6a4-1c3d-4e5f-9a7b-6c8d0e2f4a61"
> }
> ```
>
> **occurred\_at** `string`
>
> 요청에 보낸 `timestamp`입니다. 이 시각이 속한 KST 달의 사용량이 됩니다.
>
> **received\_at** `string`
>
> MeterEngine이 이벤트를 받은 시각입니다. 집계 마감에 들었는지를 이 시각으로 판단합니다. 요청에 실어 보내도 무시됩니다.
>
> **request\_id** `string`
>
> 이 이벤트를 처음 저장한 요청의 응답 헤더 `X-Request-ID` 값입니다. 연동 쪽 로그에 남긴 `X-Request-ID`와 맞춰 볼 수 있습니다.
>
> **actor\_type** `string`
>
> 보낸 주체입니다. API 키로 보냈으면 `api_key`이고, 이때 `actor_id`는 그 키의 id입니다.
>
> `404 event_not_found`가 오면 그 `transaction_id`로 저장된 이벤트가 현재 업무 환경에 없습니다. [이벤트가 청구에 안 보일 때](https://docs.meterengine.com/troubleshooting/events-not-billed.md)의 수집 단계부터 보세요.

> [tab] 콘솔
>
> '수집 로그' 화면의 '이벤트 또는 고객 찾기'에 전송 ID(`transaction_id`)를 넣습니다. 고객 이름이나 외부 고객 ID로도 찾을 수 있습니다. 이벤트를 열면 '발생 시각 (KST)', '수신 시각 (KST)'과 전송 속성이 보입니다.
>
> '수집 로그'는 기본으로 이번 달 이벤트를 발생 시각 최신순으로 보여 줍니다. 다른 달에 보낸 이벤트는 '조회 월'을 바꿔서 찾습니다.

> [!NOTE]
>
> 이벤트 조회 응답의 시각은 오프셋이 붙은 ISO 8601 문자열이지만 오프셋이 KST(+09:00)라는 보장은 없습니다. 위 예시의 `2026-11-05T01:00:00Z`는 KST로 2026-11-05 10:00입니다. 어느 달에 들었는지는 KST로 바꿔서 판단하세요.

**2. 사용량으로 집계됐는지 본다**

이벤트가 저장돼도 그 `type`을 집계하는 미터가 없거나, 미터가 세는 속성 값이 집계할 수 없는 형식이면 사용량에 들지 않습니다.

> [tab] API
>
> ```bash curl theme={null}
> curl -sS "https://meterengine.com/v1/usage?month=2026-11" \
>   -H "Authorization: Bearer me_test_xxxxxxxx"
> ```
>
> ```json 200 응답 theme={null}
> {
>   "month": "2026-11",
>   "billable_metric_usages": [
>     {
>       "code": "tokens",
>       "name": "토큰 사용량",
>       "event_type": "llm_usage",
>       "aggregation": "sum",
>       "target_property": "tokens",
>       "customers": [
>         {
>           "customer_id": "3f6c2a1e-8b4d-4e2a-9c71-5d0b8e2f4a10",
>           "customer_name": "에이콘랩",
>           "quantity": 1234,
>           "dimension_usages": [
>             {
>               "dimension_values": { "model": "small" },
>               "quantity": 1234,
>               "raw_quantity": 1234,
>               "raw_quantity_numerator": 1234,
>               "raw_quantity_denominator": 1
>             }
>           ],
>           "raw_quantity": 1234,
>           "raw_quantity_numerator": 1234,
>           "raw_quantity_denominator": 1
>         }
>       ],
>       "unit_size": 1,
>       "rounding_mode": "none",
>       "rounding_precision": 0,
>       "percentile": null
>     }
>   ]
> }
> ```
>
> * 미터마다 그 업무 환경의 모든 고객이 나옵니다. 이벤트가 없는 고객은 `quantity`가 0이고 `dimension_usages`가 빈 배열입니다.
> * `dimension_usages`는 미터의 차원 속성 값 조합마다 나눈 수량입니다. 청구는 이 조합별 수량에 그 조합의 단가를 곱합니다.
> * 고객의 `quantity`는 그 고객의 이벤트 전체를 따로 집계한 값이라 조합별 수량을 더한 값과 다를 수 있습니다. 청구 금액을 맞춰 볼 때는 조합별 수량을 보세요.
> * `raw_quantity`는 단위 변환 전 집계량이고 `quantity`는 `unit_size` 나눗셈과 반올림을 적용한 값입니다.
> * 사용량 응답에는 금액이 없습니다. 금액은 다음 단계의 청구 예정액에서 봅니다.

> [tab] 콘솔
>
> '사용량' 화면에서 달을 고르면 미터와 고객별 수량이 보입니다. 필터 줄에는 마감 전인 달이면 '집계 마감'에 마감 예정 시각이, 마감이 지난 달이면 '집계 기준'에 그 시각까지 받은 사용량이라는 표시가 나옵니다.
>
> 화면 위 '수집 확인과 정정'에는 청구에서 빠지거나 확인이 필요한 이벤트가 항목별 건수로 나옵니다. 건수가 있는 항목은 대상 이벤트로 가는 링크가 붙습니다.
>
> | 항목 | 뜻 | 이어지는 화면 |
> | - | - | - |
> | 미터와 연결되지 않은 유형 | 이벤트의 `type`을 집계하는 미터가 없습니다 | '이벤트 매핑 진단' |
> | 집계할 수 없는 속성 | 미터가 세는 속성이 없거나 값의 형식이 집계 방식에 맞지 않습니다 | '이벤트 매핑 진단' |
> | 미래 시각의 이벤트 | 발생 시각이 아직 오지 않아 집계에 들지 않습니다 | '수집 로그' |
> | 음수 수량의 이벤트 | 미터가 세는 속성 값이 음수입니다. 집계에는 반영됩니다 | '청구 검토' |
>
> 판정은 미터마다 하므로 같은 이벤트가 여러 항목에 잡힐 수 있습니다. 같은 건수는 `GET /v1/unbilled-events?month=2026-11`의 `unmatched_type`, `non_numeric_value`, `future_timestamp`, `negative_quantity`로도 볼 수 있습니다.

**3. 청구 예정액에 반영됐는지 본다**

사용량에 단가가 붙어야 금액이 나옵니다. 단가는 미터의 차원 속성 값 조합마다 따로 정하므로, 사용량이 있어도 그 조합의 단가가 없으면 금액에 들지 않습니다.

> [tab] API
>
> ```bash curl theme={null}
> curl -sS "https://meterengine.com/v1/invoices/draft?month=2026-11" \
>   -H "Authorization: Bearer me_test_xxxxxxxx"
> ```
>
> ```json 200 응답 theme={null}
> {
>   "month": "2026-11",
>   "calculated_at": "2026-11-05T10:05:00.123456+09:00",
>   "auto_finalize_enabled": false,
>   "auto_finalize_at": null,
>   "auto_finalize_running": false,
>   "total_amount": 2460,
>   "customers": [
>     {
>       "customer_id": "3f6c2a1e-8b4d-4e2a-9c71-5d0b8e2f4a10",
>       "customer_name": "에이콘랩",
>       "amount": 2460,
>       "lines": [
>         {
>           "billable_metric_code": "tokens",
>           "target_property": "tokens",
>           "dimension_values": { "model": "small" },
>           "quantity": 1234,
>           "unit_price": 2,
>           "amount": 2460,
>           "line_type": "per_unit",
>           "tier_index": 0,
>           "quantity_numerator": 1234,
>           "quantity_denominator": 1
>         }
>       ],
>       "unpriced_usages": [],
>       "negative_usages": [],
>       "auto_finalize_held": false
>     }
>   ]
> }
> ```
>
> * 1234 x 2원 = 2468원이지만 라인 금액은 2460원입니다. 금액은 라인마다 10원 미만을 버립니다. 자세한 규칙은 [예정액, 확정액, 수납액](https://docs.meterengine.com/concepts/amounts.md)을 보세요.
> * 청구 예정액은 세금을 뺀 공급가액이고, 결제는 세금을 포함한 확정 금액으로 합니다.
> * 단가가 없는 조합의 사용량은 `lines`에 없고 `unpriced_usages`에 미터 code, 조합, 수량으로 나옵니다.
> * 조합의 변환 전 집계량이 음수면 0원으로 보고 `lines`에서 빼며 `negative_usages`에 나옵니다.
> * 청구 예정액은 조회할 때마다 다시 계산합니다. 그 달을 이미 확정한 고객은 나오지 않으므로 확정한 금액은 `GET /v1/invoices`로 봅니다.

> [tab] 콘솔
>
> '청구 검토' 화면에서 달을 고르면 고객별 청구 예정액과 라인이 보입니다. 단가가 없는 조합의 사용량은 라인과 따로 표시되고 금액에 들지 않습니다.
>
> '개요' 화면의 '확인할 항목'에도 그 달에 해당하는 조합이 있으면 '단가 없는 사용량'과 '음수 합계' 조합 수가 나옵니다. '단가 없는 사용량'은 '청구 검토'와 '이벤트 매핑 진단'으로, '음수 합계'는 '청구 검토'로 이어집니다.

어느 단계에서 숫자가 끊겼는지에 따라 원인이 다릅니다. 증상별 원인과 조치는 [이벤트가 청구에 안 보일 때](https://docs.meterengine.com/troubleshooting/events-not-billed.md)를 보세요.

## 시각의 종류

확인할 때 헷갈리기 쉬운 것은 시각입니다. 아래 시각은 각각 다른 것을 정합니다.

| 시각 | 응답 필드 | 정하는 것 |
| - | - | - |
| 발생 시각 | `occurred_at` (보낼 때는 `timestamp`) | 어느 달의 사용량인지. 달은 KST 기준입니다 |
| 수신 시각 | `received_at` | 그 달 집계 마감 전에 받았는지 |
| 지금 | 없음 | 발생 시각이 지금보다 뒤인 이벤트는 그 시각이 올 때까지 집계하지 않습니다 |

청구 월은 한국 시간(KST) 기준 달력 월입니다. 지난달 사용량은 다음 달 1일 13:00 KST까지 받은 것만 청구됩니다. 마감 뒤에 받은 지난달 이벤트는 저장되고 '수집 로그'에도 보이지만 사용량과 청구 예정액에는 들지 않습니다. 규칙 전체는 [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md)을 보세요.

## 확인할 때 주의할 점

* 사용량 조회, 청구 예정액 조회, '이벤트 매핑 진단'은 요청할 때마다 그 달 이벤트를 다시 집계합니다. 이벤트가 많은 달일수록 응답에 시간이 걸리니 연동 코드에서 짧은 간격으로 반복해 부르지 마세요. 한 달 치 숫자를 자기 기록과 맞추는 순서는 [서버 조회와 CSV 내보내기](https://docs.meterengine.com/reference/search-and-export.md)를 보세요.
* '이벤트 매핑 진단'은 지금의 미터 정의와 단가로 다시 진단합니다. 단가를 등록하면 그 조합의 행은 목록에서 사라집니다.
* 이벤트 수집 요청은 감사 기록에 나오지 않으니 저장된 이벤트와 수집 거절 기록의 `request_id`, `transaction_id`로 찾습니다. '수집 로그'의 이벤트 상세에 '이 요청의 감사 기록 보기' 링크가 있지만 그 요청은 '감사 기록'에 없습니다. 자세한 내용은 [오류 응답과 X-Request-ID](https://docs.meterengine.com/api-basics/errors.md)를 보세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.