---
title: "Get YouTube Top-Artist Chart (weekly)"
method: GET
path: "/api/charts/youtube/artists"
tags: ["Charts"]
---

# Get YouTube Top-Artist Chart (weekly)

`GET /api/charts/youtube/artists`

## Request

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

Return the YouTube weekly top-artist chart for a given `country_code` and `date`. Each row carries the chart row + per-artist `rankStats` and `viewStats` histories, plus `image_url` hydrated from `Artist.getBasicInfoBatch`. Data is updated weekly on Thursdays.

## Query parameters

- `country_code` string, required: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').
- `date` string, date-time: Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`.
- `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate.
- `latest` boolean: If true, use the most recently available date and ignore `date`.

## Response `200`

Success

- object
  - `obj` object, required
    - `length` integer, required: Number of chart rows in `data`.
    - `data` object[], required: Chart rows ordered by rank (1 = highest).
      - `cm_artist` integer, nullable: Chartmetric artist ID.
      - `youtube_artist` string, nullable: YouTube artist channel link/ID.
      - `name` string, nullable: Artist name.
      - `image_url` string, nullable: Artist image URL.
      - `rank` integer, nullable: Current chart rank (1 = top).
      - `position` integer, nullable: Current chart position. Same value as `rank`.
      - `view_count` integer, nullable: Total view count across the artist's YouTube channel.
      - `subscriber_count` integer, nullable: YouTube subscriber count.
      - `added_at` string, date-time, nullable: Timestamp the artist was added to the chart.
      - `velocity` number, float, nullable: Rank-velocity signal (positive = climbing).
      - `pre_rank` integer, nullable: Position on the previous chart period.
      - `peak_rank` integer, nullable: Best (lowest-numbered) rank reached.
      - `peak_date` string, date-time, nullable: Date `peak_rank` was achieved.
      - `time_on_chart` union: Length of time on the chart (integer count of periods or duration string).
        - integer
        - string
      - `rankStats` object[], nullable: Historical rank samples.
        - `rank` integer, nullable: Rank at `timestp` (1 = top).
        - `timestp` string, date-time, nullable: Timestamp of the rank sample.
      - `viewStats` object[], nullable: Historical view-count samples.
        - `views` integer, nullable: View count at `timestp`.
        - `timestp` string, date-time, nullable: Timestamp of the view-count sample.

---

[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)