Usage

SocFlow API의 사용량과 작업 통계를 조회할 수 있습니다. 이 엔드포인트를 통해 API 호출 통계, 엔드포인트별 사용량, 작업(Job) 실행 통계 등을 확인할 수 있습니다.

사용량 데이터는 실시간으로 집계되며, 기간을 지정하여 특정 기간의 통계만 조회할 수도 있습니다. 이 정보는 API 사용 패턴 분석과 최적화에 유용합니다.

GET/v1/usage

API 사용량 조회

이 엔드포인트는 현재 사용자의 API 사용량 통계를 반환합니다. API 호출 횟수, 성공/실패 비율, 응답 시간, 작업 실행 통계 등이 포함됩니다.

인증

이 엔드포인트는 인증이 필요합니다. API 키를 X-Secret-Token 헤더에 포함해야 합니다.

사용량 데이터는 인증된 사용자의 데이터만 조회할 수 있습니다. SocFlow 웹 서비스에서 사용한 데이터도 포함됩니다.

요청

GET

/v1/usage

curl --location 'https://api.socflow.app/api/v1/usage' \
--header 'X-Secret-Token: {YOUR_API_KEY}'

응답

200

{
  "success": true,
  "data": {
    "api_usage": {
      "total_requests": 150,
      "successful_requests": 145,
      "failed_requests": 5,
      "total_duration_ms": 87500,
      "average_duration_ms": 583,
      "by_endpoint": [
        {
          "endpoint": "/api/v1/posts",
          "method": "POST",
          "count": 45,
          "successful_count": 43,
          "failed_count": 2
        },
        {
          "endpoint": "/api/v1/accounts/social",
          "method": "GET",
          "count": 38,
          "successful_count": 38,
          "failed_count": 0
        },
        {
          "endpoint": "/api/v1/media",
          "method": "POST",
          "count": 25,
          "successful_count": 24,
          "failed_count": 1
        }
      ],
      "by_status_code": [
        {
          "status_code": 200,
          "count": 120
        },
        {
          "status_code": 201,
          "count": 25
        },
        {
          "status_code": 400,
          "count": 3
        },
        {
          "status_code": 500,
          "count": 2
        }
      ]
    },
    "job_usage": {
      "total_jobs": 45,
      "container_jobs_usage": {
        "total": 20,
        "completed": 19,
        "failed": 1,
        "pending": 0,
        "average_duration_ms": 4200
      },
      "carousel_jobs_usage": {
        "total": 5,
        "completed": 5,
        "failed": 0,
        "pending": 0,
        "average_duration_ms": 3800
      },
      "publish_jobs_usage": {
        "total": 20,
        "completed": 19,
        "failed": 1,
        "pending": 0,
        "average_duration_ms": 2100
      },
      "by_job_type": [
        {
          "job_type": "container_create",
          "total": 20,
          "completed": 19,
          "failed": 1,
          "pending": 0,
          "average_duration_ms": 4200
        },
        {
          "job_type": "publish_content",
          "total": 20,
          "completed": 19,
          "failed": 1,
          "pending": 0,
          "average_duration_ms": 2100
        },
        {
          "job_type": "carousel_upload",
          "total": 5,
          "completed": 5,
          "failed": 0,
          "pending": 0,
          "average_duration_ms": 3800
        }
      ]
    },
    "period": {
      "start_date": null,
      "end_date": null
    }
  }
}

쿼리 파라미터

사용량을 조회할 기간을 지정할 수 있습니다.

Name
start_date
Type
number
Description
(선택) 조회 시작 시각 (Unix timestamp, milliseconds). 이 값 이후의 데이터만 포함됩니다.
Name
end_date
Type
number
Description
(선택) 조회 종료 시각 (Unix timestamp, milliseconds). 이 값 이전의 데이터만 포함됩니다.

기간 필터링 예시

# 2024년 1월 1일 ~ 1월 31일 데이터 조회
curl --location 'https://api.socflow.app/api/v1/usage?start_date=1704067200000&end_date=1706745600000' \
--header 'X-Secret-Token: {YOUR_API_KEY}'

응답 필드

API Usage 객체

Name
total_requests
Type
number
Description
전체 API 요청 수
Name
successful_requests
Type
number
Description
성공한 요청 수 (HTTP 2xx, 3xx)
Name
failed_requests
Type
number
Description
실패한 요청 수 (HTTP 4xx, 5xx)
Name
total_duration_ms
Type
number
Description
전체 요청 처리 시간 (밀리초)
Name
average_duration_ms
Type
number
Description
평균 요청 처리 시간 (밀리초)
Name
by_endpoint
Type
array
Description
엔드포인트별 사용량 배열
Name
by_status_code
Type
array
Description
HTTP 상태 코드별 요청 수 배열

Endpoint Usage 객체

Name
endpoint
Type
string
Description
엔드포인트 경로 (예: /api/v1/posts)
Name
method
Type
string
Description
HTTP 메소드 (GET, POST, PUT, DELETE)
Name
count
Type
number
Description
해당 엔드포인트의 총 요청 수
Name
successful_count
Type
number
Description
성공한 요청 수
Name
failed_count
Type
number
Description
실패한 요청 수

Job Usage 객체

Name
total_jobs
Type
number
Description
전체 작업 수
Name
container_jobs_usage
Type
object
Description
미디어 컨테이너 생성 작업 통계
Name
carousel_jobs_usage
Type
object
Description
캐러셀(다중 이미지) 업로드 작업 통계
Name
publish_jobs_usage
Type
object
Description
게시물 발행 작업 통계
Name
by_job_type
Type
array
Description
작업 타입별 통계 배열

Job Type Usage 객체

Name
job_type
Type
string
Description
작업 타입 (container_create, carousel_upload, publish_content)
Name
total
Type
number
Description
전체 작업 수
Name
completed
Type
number
Description
완료된 작업 수
Name
failed
Type
number
Description
실패한 작업 수
Name
pending
Type
number
Description
대기 중인 작업 수
Name
average_duration_ms
Type
number | null
Description
평균 처리 시간 (밀리초). 작업이 없으면 null

사용 예시

월별 사용량 조회

async function getThisMonthUsage() {
  const now = new Date()
  const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1)
  const startDate = startOfMonth.getTime()

  const response = await fetch(
    `https://api.socflow.app/api/v1/usage?start_date=${startDate}`,
    {
      headers: {
        'X-Secret-Token': process.env.SOCFLOW_API_KEY,
      },
    },
  )

  const result = await response.json()
  return result.data
}

const usage = await getThisMonthUsage()
console.log(`이번 달 API 호출: ${usage.api_usage.total_requests}회`)
console.log(
  `성공률: ${((usage.api_usage.successful_requests / usage.api_usage.total_requests) * 100).toFixed(1)}%`,
)

사용량 대시보드 구현

async function createUsageDashboard() {
  const response = await fetch('https://api.socflow.app/api/v1/usage', {
    headers: {
      'X-Secret-Token': process.env.SOCFLOW_API_KEY,
    },
  })

  const result = await response.json()
  const { api_usage, job_usage } = result.data

  console.log('=== API 사용량 대시보드 ===\n')

  // API 통계
  console.log('📊 API 통계:')
  console.log(`  총 요청: ${api_usage.total_requests}`)
  console.log(`  성공: ${api_usage.successful_requests}`)
  console.log(`  실패: ${api_usage.failed_requests}`)
  console.log(`  평균 응답시간: ${api_usage.average_duration_ms}ms\n`)

  // 가장 많이 사용된 엔드포인트 TOP 3
  console.log('🔝 TOP 3 엔드포인트:')
  api_usage.by_endpoint.slice(0, 3).forEach((endpoint, index) => {
    console.log(
      `  ${index + 1}. ${endpoint.method} ${endpoint.endpoint}: ${endpoint.count}회`,
    )
  })
  console.log('')

  // 작업 통계
  console.log('⚙️ 작업 통계:')
  console.log(`  총 작업: ${job_usage.total_jobs}`)
  console.log(
    `  미디어 컨테이너: ${job_usage.container_jobs_usage.completed}/${job_usage.container_jobs_usage.total}`,
  )
  console.log(
    `  게시물 발행: ${job_usage.publish_jobs_usage.completed}/${job_usage.publish_jobs_usage.total}`,
  )
  console.log('')

  return result.data
}

await createUsageDashboard()

에러율 모니터링

async function monitorErrorRate() {
  const response = await fetch('https://api.socflow.app/api/v1/usage', {
    headers: {
      'X-Secret-Token': process.env.SOCFLOW_API_KEY,
    },
  })

  const result = await response.json()
  const { api_usage } = result.data

  const errorRate = (api_usage.failed_requests / api_usage.total_requests) * 100

  console.log(`에러율: ${errorRate.toFixed(2)}%`)

  // 에러율이 5% 이상이면 경고
  if (errorRate > 5) {
    console.warn('⚠️ 경고: 에러율이 높습니다!')

    // 상태 코드별 분석
    console.log('\n상태 코드 분포:')
    api_usage.by_status_code.forEach((status) => {
      console.log(`  ${status.status_code}: ${status.count}회`)
    })
  }

  return errorRate
}

await monitorErrorRate()

사용량 데이터는 실시간으로 집계되며, 약간의 지연이 있을 수 있습니다. 정확한 청구 정보는 대시보드에서 확인하세요.