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

# Usage Query

> Query remaining quota for the current API Key account, also used to validate the API Key

<Note>
  `remaining_paid_pages` is the sum of remaining pages across all active paid plans. `remaining_free_pages_today` is the remaining free quota for today. `remaining_free_pages_this_month` is the remaining free quota for this month.
</Note>

If you want the shortest path to a working integration, start with [SoMark API](/en/documentation/api); for the full endpoint list and auth summary, go back to the [API overview](/en/api-reference/index); free quota details are in [Free tier rules](/en/documentation/free-tier-rules).


## OpenAPI

````yaml POST /usage
openapi: 3.0.3
info:
  title: SoMark 文档智能 API
  description: >-
    SoMark 文档解析服务 API，支持 PDF、图片、Word、PPT 和 Excel 文件解析，输出 Markdown / JSON / DOCX
    格式。
  version: 1.0.0
servers:
  - url: https://somark.cn/api/v1
security: []
paths:
  /usage:
    post:
      summary: 用量查询
      description: 查询当前 API Key 关联账号的剩余解析额度，同时可用于验证 API Key 有效性。
      operationId: getUsage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - api_key
              properties:
                api_key:
                  type: string
                  description: API 密钥，格式 `sk-***`
                  example: sk-***
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            import requests

            url = "https://somark.cn/api/v1/usage"

            data = {
                "api_key": "sk-***",
            }

            response = requests.post(url, data=data)
            print(response.json())
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://somark.cn/api/v1/usage \
              -F "api_key=sk-***"
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        code:
          type: integer
          description: 状态码，`0` 为成功，非 `0` 见[错误码](/api-reference/errors)
          example: 0
        message:
          type: string
          description: 错误信息。成功时通常为空字符串。
          example: ''
        data:
          type: object
          description: 当前 API Key 对应账号的剩余额度信息。
          properties:
            remaining_paid_pages:
              type: integer
              description: 所有未过期付费套餐的剩余页数之和
              example: 104410
            remaining_free_pages_today:
              type: integer
              description: 今日剩余免费页数
              example: 295
            remaining_free_pages_this_month:
              type: integer
              description: 本月剩余免费页数
              example: 578
            dashboard_url:
              type: string
              description: 控制台页面 URL
              example: https://somark.tech/workbench
      example:
        code: 0
        message: ''
        data:
          remaining_paid_pages: 104410
          remaining_free_pages_today: 295
          remaining_free_pages_this_month: 578
          dashboard_url: https://somark.tech/workbench

````