---
title: "Twitch User Charts"
method: GET
path: "/api/charts/twitch/users"
tags: ["Charts"]
---

# Twitch User Charts

`GET /api/charts/twitch/users`

## Request

- Base URL: `https://api.chartmetric.com`
- URL: `https://api.chartmetric.com/api/charts/twitch/users`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/docs/api/charts/twitch/users/get.ts> (a function with typed inputs; its response is checked against the schema)

Twitch user charts by `duration` (daily/weekly/monthly) and `type` (followers or view counts). Handler builds the source `twitch_*_chart` table dynamically, then merges platform-linked artist info and historical `rankStats` from `QUERY_GET_USER_RANKINGS.TWITCH`.

## Query parameters

- `date` string, date-time: Charting date (`YYYY-MM-DD`); defaults to the latest available chart.
- `since` string, date-time: Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`.
- `limit` integer: Maximum entries returned (max 500).
- `duration` 'daily' | 'weekly' | 'monthly', required: Chart duration. `daily` requires `type=followers`; `monthly` requires `type=viewer_hours`.
- `type` 'followers' | 'viewer_hours': Twitch chart type (`followers` or `viewer_hours`). Constrained by `duration` (see error messages).
- `latest` boolean: If true, use the most recently available date and ignore `since`.

## Response `200`

Success

- object
  - `obj` object
    - `length` integer, nullable: Number of chart rows in `data`.
    - `data` object[], nullable: Chart rows ordered by rank (1 = highest).
      - `rank` integer, nullable: Current chart rank (1 = top).
      - `pre_rank` integer, nullable: Position on the previous chart period.
      - `peak_rank` integer, nullable: Best (lowest-numbered) rank reached.
      - `peak_date` union: Date `peak_rank` was achieved.
        - string, date-time
        - string
      - `added_at` union: Timestamp the user was added to the chart.
        - string, date-time
        - string
      - `velocity` number, float, nullable: Rank-velocity signal (positive = climbing).
      - `time_on_chart` union: Length of time on the chart.
        - string
        - number, float
      - `twitch_user` union: Twitch user handle/ID.
        - integer
        - string
      - `followers` union: Twitch followers count.
        - number, float
        - string
      - `weekly_followers` union: Followers gained in the last 7 days.
        - number, float
        - string
      - `monthly_followers` union: Followers gained in the last 30 days.
        - number, float
        - string
      - `count` union: Daily viewer-hours count.
        - number, float
        - string
      - `weekly_count` union: Weekly viewer-hours count.
        - number, float
        - string
      - `monthly_count` union: Monthly viewer-hours count.
        - number, float
        - string
      - `name` string, nullable: Twitch user / artist name.
      - `image_url` string, nullable: Profile image URL.
      - `link` string, nullable: Twitch profile link.
      - `cm_artist` integer, nullable: Chartmetric artist ID linked to the Twitch user.
      - `rankStats` object[], nullable: Historical rank + followers samples.
        - `rank` integer, nullable: Rank at `timestp` (1 = top).
        - `followers` union: Followers count at `timestp` (Twitch).
          - number, float
          - string
        - `timestp` union: Timestamp of the sample.
          - string, date-time
          - string

---

[API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)