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

# Get Usage History

> Your daily upload activity for the last 365 days, with summary stats.

Fetch your daily upload activity for the last 365 days, with summary stats. This is the data behind the Upload Activity heatmap on the Billing & Usage settings page.

## Behavior

* Returns activity for the key's owner only. Team keys get `401`.
* `history` is oldest first. Days with no uploads are left out, so the array is sparse.
* `bytes` and `upload_count` count successful uploads only.
* `stats.upload_count` and `stats.total_bytes` cover the whole 365-day window.
* `stats.current_streak` counts consecutive days with uploads ending today (UTC). It is `0` if you have not uploaded today.
* `stats.biggest_day` is `null` when there is no activity in the window.
* All days are UTC, formatted `YYYY-MM-DD`.

## Examples

```bash theme={null}
curl "https://api.snipp.gg/usage-history" \
  -H "api-key: YOUR_API_KEY"
```

## Responses

```json theme={null}
{
  "history": [
    {
      "day": "2026-09-28",
      "bytes": 5242880,
      "upload_count": 3
    },
    {
      "day": "2026-09-30",
      "bytes": 1048576,
      "upload_count": 1
    }
  ],
  "stats": {
    "total_bytes": 6291456,
    "upload_count": 4,
    "active_days": 2,
    "current_streak": 1,
    "biggest_day": {
      "day": "2026-09-28",
      "bytes": 5242880
    },
    "window_days": 365
  }
}
```

## Errors

| Status | Type | When |
| - | - | - |
| `401` | `unauthorized` | Missing or invalid key |
| `403` | `suspended` | Your account is suspended |
| `429` | `rate_limited` | More than 30 requests per minute |


## OpenAPI

````yaml api-reference/openapi.json GET /usage-history
openapi: 3.0.0
info:
  title: Snipp.gg API
  description: Image and video hosting API. Upload, manage, and share media files.
  version: 3.0.0
servers:
  - url: https://api.snipp.gg
    description: Default. Load-balanced across regions. No upload cap.
  - url: https://eu-west-1.api.snipp.gg
    description: EU West regional endpoint. Pins uploads and storage to EU West.
  - url: https://us-west-1.api.snipp.gg
    description: US West regional endpoint. Pins uploads and storage to US West.
  - url: https://flux.snipp.gg
    description: Alternative host. Capped at 100 MB per upload.
security:
  - apiKeyAuth: []
paths:
  /usage-history:
    get:
      summary: Get Usage History
      description: Your daily upload activity for the last 365 days, with summary stats.
      operationId: getUsageHistory
      responses:
        '200':
          description: Success
          headers:
            request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageHistory'
              example:
                history:
                  - day: '2026-09-28'
                    bytes: 5242880
                    upload_count: 3
                  - day: '2026-09-30'
                    bytes: 1048576
                    upload_count: 1
                stats:
                  total_bytes: 6291456
                  upload_count: 4
                  active_days: 2
                  current_streak: 1
                  biggest_day:
                    day: '2026-09-28'
                    bytes: 5242880
                  window_days: 365
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '405':
          $ref: '#/components/responses/E405'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
components:
  headers:
    RequestId:
      description: Unique ID for the request. Include it when contacting support.
      schema:
        type: string
        format: uuid
  schemas:
    UsageHistory:
      type: object
      properties:
        history:
          type: array
          items:
            type: object
            properties:
              day:
                type: string
                format: date
                example: '2026-09-30'
              bytes:
                type: integer
              upload_count:
                type: integer
            required:
              - day
              - bytes
              - upload_count
        stats:
          type: object
          properties:
            total_bytes:
              type: integer
            upload_count:
              type: integer
            active_days:
              type: integer
            current_streak:
              type: integer
            biggest_day:
              type: object
              properties:
                day:
                  type: string
                  format: date
                  example: '2026-09-30'
                bytes:
                  type: integer
              required:
                - day
                - bytes
              nullable: true
            window_days:
              type: integer
          required:
            - total_bytes
            - upload_count
            - active_days
            - current_streak
            - biggest_day
            - window_days
      required:
        - history
        - stats
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
      description: Every non-2xx response has this body.
    ErrorDetail:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        message:
          type: string
          description: Human-readable sentence. Do not match on it; use `type`.
        username:
          type: string
          description: >-
            `suspended` on `GET /users/{id}` only: the suspended user's
            username.
        quota:
          type: integer
          description: '`quota_exceeded` only: weekly quota in bytes.'
        used:
          type: integer
          description: '`quota_exceeded` only: bytes used in the current window.'
        resets_at:
          type: string
          format: date-time
          description: '`quota_exceeded` only: when the weekly window resets.'
          nullable: true
        failed:
          type: array
          items:
            $ref: '#/components/schemas/FailedFile'
          description: '`upload_failed` only: one entry per file.'
      required:
        - type
        - message
    ErrorType:
      type: string
      enum:
        - invalid_request
        - unauthorized
        - forbidden
        - suspended
        - blocked
        - moderated
        - plan_required
        - not_found
        - method_not_allowed
        - file_too_large
        - unsupported_type
        - quota_exceeded
        - rate_limited
        - upload_failed
        - internal
        - unavailable
      description: Machine-readable error category. See [Errors](/concepts/errors).
    FailedFile:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based position of the file in the request.
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - index
        - error
      description: >-
        A file that was not stored. `error` has the same shape as a top-level
        error.
  responses:
    E401:
      description: Missing or invalid key
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E403:
      description: Not allowed
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E405:
      description: Method not allowed
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
        Allow:
          description: Methods this path accepts.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E429:
      description: Rate limited
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E500:
      description: Internal error
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Your API key from the Snipp Console

````

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