지표 값 적재

매달 MRR, 매일 배포 횟수처럼 다른 시스템에 있는 숫자를 GoalTrack 지표로 보내 목표선과 함께 봅니다. 필요한 것은 수집 주소와 metrics:ingest 권한 Key 두 가지입니다.

1. 수집 주소 복사

수집 주소는 지표마다 하나입니다. 두 곳에서 복사할 수 있습니다.

지표 화면에서 값을 넣을 지표를 연 뒤 「수집 주소」 카드의 복사 버튼.
설정 › API 의 「수집 주소」 카드에서 지표를 고른 뒤 복사.

주소를 손으로 조립하지 말고 화면에서 복사해 쓰세요. 화면이 주는 주소가 서버가 받는 주소와 같은 함수에서 만들어집니다. 주소 자체는 비밀이 아닙니다 — Key 없이 보낸 요청은 전부 거절됩니다.

2. Key 발급

API Key 에서 「지표 적재」(metrics:ingest) 권한만 고른 Key 를 만드는 것을 권합니다. 이 Key 는 값을 넣을 수만 있고 이슈를 읽거나 쓸 수 없습니다. 보기 권한(viewer) 멤버는 이 권한을 고를 수 없습니다.

3. 값 보내기

한 건

curl -X POST "$GOALTRACK_INGEST_URL" \
  -H "Authorization: Bearer $GOALTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 12500000, "ts": "2026-10-01T00:00:00Z", "labels": { "plan": "pro" } }'

필드	필수	설명
`value`	예	숫자, 또는 소수를 담은 문자열(`"1234.56"`). 절댓값이 10¹⁴ 보다 작아야 합니다.
`ts`	아니오	ISO 8601 시각 — 초까지 쓰고 시간대(`Z` 또는 `+09:00`)를 붙입니다(`2026-10-01T00:00:00Z`). 초를 빼면(`2026-10-01T00:00Z`) 400 입니다. 빼면 지금입니다. 지표의 기본 단위(일·주·월)로 내림해 저장합니다.
`labels`	아니오	`{ "키": "값" }`. 키는 지표에 정의된 차원이어야 합니다 — 아니면 `400 INVALID_LABELS`. 값의 앞뒤 공백은 다듬어 저장합니다(`" web"` = `"web"`). 다듬으면 빈 값이면 `400 METRIC_LABEL_EMPTY` 입니다.
`source`	아니오	빼면 `webhook` 으로 기록되어 화면에서 사람이 넣은 값(`manual`)과 구분됩니다.

성공하면 201 과 저장된 값이 돌아옵니다.

여러 건(배치)

수집 주소 끝에 /bulk 를 붙이고 rows 배열로 보냅니다. 한 번에 1~1000행이고, 행의 모양은 한 건과 같습니다.

curl -X POST "$GOALTRACK_INGEST_URL/bulk" \
  -H "Authorization: Bearer $GOALTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "value": 11800000, "ts": "2026-09-01T00:00:00Z" }, { "value": 12500000, "ts": "2026-10-01T00:00:00Z" } ] }'

성공하면 201 과 { "count": 2 } 가 돌아옵니다. 배치는 Key 하나당 분당 20번까지입니다(한 건 보내기는 120번).

AI 에이전트에게 맡기기

지표 화면 「자동으로 넣기」의 AI 에이전트 지시문을 셸 명령을 실행할 수 있는 에이전트에게 주면, 에이전트가 위의 한 건 보내기 명령으로 값을 넣습니다. 에이전트가 도는 환경에도 같은 metrics:ingest Key 를 GOALTRACK_API_KEY 환경 변수로 넣어 두세요. AI 에이전트 키(gtag_)로는 지표 값을 넣을 수 없습니다 — 에이전트 키는 이슈·댓글·상태 요청만 엽니다.

다시 보내도 안전합니다

같은 지표에 같은 시각(내림한 단위 기준)·같은 labels 로 다시 보내면 덮어씁니다. 실패한 요청을 그대로 재시도해도 값이 두 번 쌓이지 않습니다.

자주 만나는 거절

응답	이유
`401 UNAUTHORIZED`	Key 가 없거나 틀렸습니다.
`403 INSUFFICIENT_SCOPE`	Key 에 `metrics:ingest` 권한이 없습니다.
`403 WRITER_ROLE_REQUIRED`	Key 를 발급한 사람이 지금 보기 권한(viewer)입니다.
`404 NOT_FOUND`	지표가 없거나 이 Key 의 워크스페이스 지표가 아닙니다.
`409 METRIC_ARCHIVED`	보관된 지표입니다. 지표 화면에서 보관을 해제하세요.

전체 목록은 에러 코드 에 있습니다.