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

> ## Agent Instructions
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt

# Get creator rankings

> Read one reviewed ranking with explicit market and period. Bindings must agree on the ranking identity; GMV, popularity and room-specific leaderboards are not interchangeable.

The request and response panels use the schemas published by this API. Conditional requirements and allowed combinations are part of the request schema. Check the complete schema before combining filters or identities.

## Billing

| Input | Price unit | Price (USD) |
| - | - | - |
| /input/ranking\_key = bilibili.follower\_growth | Per successful request | 0.02 |
| /input/ranking\_key = douyin.hot\_accounts.24h | Per successful request | 0.0034 |
| /input/ranking\_key = tiktok\_shop.creator\_gmv.last7days | Per successful request | 0.0734 |
| /input/ranking\_key = tiktok\_shop.creator\_gmv.monthly | Per 10 requested units | 0.09859 |

Only the listed values are priced; other values do not fall back to the catalog base price.
For tiktok\_shop.creator\_gmv.monthly: request price = `ceil(/input/limit / 10) × selected unit price`, rounded up once to a multiple of USD 0.0001; maximum requested quantity 100. A successful partial result still charges the requested size.
Successful delivery is charged; a normal empty result is not charged.

Obtain an input-specific quote by sending the same request with `X-AISA-Cost-Mode: quote`; quoting neither executes the Task nor reserves funds. Execution reserves the estimated request charge and settles under the rules above. Use `X-AISA-Max-Price-USD` to cap the price.

Use an `Idempotency-Key` when executing a Task. For errors, inspect `error.code`, `error.request_id`, `error.retryable` and `error.retry_hint`. A reconciliation hint requires checking the existing request before retrying; do not assume a pending settlement is a refund.


## OpenAPI

````yaml tasks/openapi.json POST /v1/tasks/creators.get_rankings
openapi: 3.1.0
info:
  title: AIsa Tasks
  version: '1'
  x-aisa-runtime-release:
    artifact_revision: 79833298e5347cbf6f763bc9313cec8dbb21b3f99e3e4bff89628c9bd47f8bed
    compiler_revision: 66257d5d26817f3e6eddc90b34155367d96513e9
    source_digest: cde7dca0fddbeccf0b89ef7580ab640c42058405baae9a3a6854c95c7c2a370e
    generation: 15127
servers:
  - url: https://api.aisa.one
security:
  - bearer: []
paths:
  /v1/tasks/creators.get_rankings:
    post:
      tags:
        - Tasks
      summary: Get creator rankings
      description: >-
        Read one reviewed ranking with explicit market and period. Bindings must
        agree on the ranking identity; GMV, popularity and room-specific
        leaderboards are not interchangeable.
      operationId: task_creators.get_rankings
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creators.get_rankings_request'
      responses:
        '200':
          description: Successful delivery or a normal empty result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.get_rankings_response'
        default:
          description: Error; use the returned HTTP status and retry guidance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.get_rankings_error'
components:
  schemas:
    creators.get_rankings_request:
      $ref: '#/components/schemas/creators.get_rankings_request.10_Request'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules: {}
    creators.get_rankings_response:
      $ref: '#/components/schemas/creators.get_rankings_response.10_Response'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules: {}
    creators.get_rankings_error:
      $ref: '#/components/schemas/creators.get_rankings_error.0_Error'
      $schema: https://json-schema.org/draft/2020-12/schema
    creators.get_rankings_request.10_Request:
      additionalProperties: false
      properties:
        input:
          $ref: '#/components/schemas/creators.get_rankings_request.9_Input'
        options:
          anyOf:
            - additionalProperties: false
              properties:
                detail:
                  anyOf:
                    - enum:
                        - ''
                        - full
                      type: string
                    - type: 'null'
                max_providers:
                  anyOf:
                    - maximum: 8
                      minimum: 0
                      type: integer
                    - type: 'null'
                providers:
                  anyOf:
                    - additionalProperties: false
                      properties:
                        exclude:
                          anyOf:
                            - items:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              type: array
                            - type: 'null'
                        only:
                          anyOf:
                            - items:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              type: array
                            - type: 'null'
                      type: object
                    - type: 'null'
                strategy:
                  anyOf:
                    - enum:
                        - ''
                        - auto
                      type: string
                    - type: 'null'
              type: object
            - type: 'null'
      required:
        - input
      type: object
    creators.get_rankings_response.10_Response:
      additionalProperties: false
      allOf:
        - else:
            properties:
              meta:
                properties:
                  delivered:
                    const: false
              result:
                type: 'null'
          if:
            properties:
              status:
                enum:
                  - found
                  - partial
          then:
            properties:
              meta:
                properties:
                  delivered:
                    const: true
              result:
                $ref: '#/components/schemas/creators.get_rankings_response.11_Result'
      properties:
        meta:
          additionalProperties: false
          properties:
            approximate_fields:
              items:
                type: string
              type:
                - array
                - 'null'
            delivered:
              type: boolean
            missing_fields:
              additionalProperties:
                description: >-
                  A stable missing-field reason, or distinct reasons separated
                  by '; '. Unrecognized internal diagnostics are reported as
                  unspecified.
                pattern: >-
                  ^(not_returned|not_supported|unparseable|continuation_failed|reference_identity_unverifiable|page_limit_reached|report_part_failed|some_account_identities_unusable|pagination_not_reported|page_or_item_limit_reached|some_distributions_unusable|quote_not_usable|quote_availability_not_returned|quote_price_not_returned|unspecified)(;
                  (not_returned|not_supported|unparseable|continuation_failed|reference_identity_unverifiable|page_limit_reached|report_part_failed|some_account_identities_unusable|pagination_not_reported|page_or_item_limit_reached|some_distributions_unusable|quote_not_usable|quote_availability_not_returned|quote_price_not_returned|unspecified))*$
                type: string
              type:
                - object
                - 'null'
          required:
            - missing_fields
            - approximate_fields
            - delivered
          type: object
        result:
          anyOf:
            - $ref: '#/components/schemas/creators.get_rankings_response.11_Result'
            - type: 'null'
        status:
          enum:
            - found
            - partial
            - not_found
          type: string
        task:
          const: creators.get_rankings
        version:
          const: 1
      required:
        - task
        - version
        - status
        - result
        - meta
      type: object
    creators.get_rankings_error.0_Error:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/creators.get_rankings_error.1_ErrorDetail'
      required:
        - error
      type: object
    creators.get_rankings_request.9_Input:
      additionalProperties: false
      allOf:
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.monthly
            required:
              - ranking_key
          then:
            properties:
              country:
                type: string
              period_value:
                pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
                type: string
              platform:
                const: tiktok
            required:
              - country
              - period_value
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.monthly
            required:
              - ranking_key
          then:
            else:
              properties:
                page:
                  anyOf:
                    - maximum: 5
                      type: integer
                    - type: 'null'
            if:
              properties:
                limit:
                  not:
                    type: 'null'
              required:
                - limit
            then:
              anyOf:
                - properties:
                    limit:
                      maximum: 1
                      type: integer
                    page:
                      anyOf:
                        - maximum: 100
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 2
                      type: integer
                    page:
                      anyOf:
                        - maximum: 50
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 3
                      type: integer
                    page:
                      anyOf:
                        - maximum: 33
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 4
                      type: integer
                    page:
                      anyOf:
                        - maximum: 25
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 5
                      type: integer
                    page:
                      anyOf:
                        - maximum: 20
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 6
                      type: integer
                    page:
                      anyOf:
                        - maximum: 16
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 7
                      type: integer
                    page:
                      anyOf:
                        - maximum: 14
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 8
                      type: integer
                    page:
                      anyOf:
                        - maximum: 12
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 9
                      type: integer
                    page:
                      anyOf:
                        - maximum: 11
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 10
                      type: integer
                    page:
                      anyOf:
                        - maximum: 10
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 11
                      type: integer
                    page:
                      anyOf:
                        - maximum: 9
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 12
                      type: integer
                    page:
                      anyOf:
                        - maximum: 8
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 14
                      type: integer
                    page:
                      anyOf:
                        - maximum: 7
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 16
                      type: integer
                    page:
                      anyOf:
                        - maximum: 6
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 20
                      type: integer
                    page:
                      anyOf:
                        - maximum: 5
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 25
                      type: integer
                    page:
                      anyOf:
                        - maximum: 4
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 33
                      type: integer
                    page:
                      anyOf:
                        - maximum: 3
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 50
                      type: integer
                    page:
                      anyOf:
                        - maximum: 2
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 100
                      type: integer
                    page:
                      anyOf:
                        - maximum: 1
                          type: integer
                        - type: 'null'
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.last7days
            required:
              - ranking_key
          then:
            properties:
              country:
                enum:
                  - US
                  - GB
                  - TH
              limit:
                anyOf:
                  - minimum: 5
                  - type: 'null'
              page:
                anyOf:
                  - maximum: 5
                  - type: 'null'
              platform:
                const: tiktok
            required:
              - country
        - if:
            not:
              properties:
                ranking_key:
                  enum:
                    - tiktok_shop.creator_gmv.monthly
              required:
                - ranking_key
          then:
            allOf:
              - not:
                  properties:
                    period_value:
                      not:
                        type: 'null'
                  required:
                    - period_value
        - if:
            properties:
              ranking_key:
                enum:
                  - douyin.hot_accounts.24h
            required:
              - ranking_key
          then:
            allOf:
              - allOf:
                  - not:
                      properties:
                        country:
                          not:
                            type: 'null'
                      required:
                        - country
              - properties:
                  page:
                    anyOf:
                      - const: 1
                      - type: 'null'
                  platform:
                    const: douyin
        - if:
            properties:
              ranking_key:
                enum:
                  - bilibili.follower_growth
            required:
              - ranking_key
          then:
            allOf:
              - allOf:
                  - not:
                      properties:
                        country:
                          not:
                            type: 'null'
                      required:
                        - country
              - properties:
                  page:
                    anyOf:
                      - const: 1
                      - type: 'null'
                  platform:
                    const: bilibili
      properties:
        country:
          anyOf:
            - description: >-
                Ranking market; required for TikTok Shop boards and forbidden
                for Douyin and Bilibili. Last-7-days supports US, GB and TH.
              enum:
                - AT
                - BE
                - BR
                - DE
                - ES
                - FR
                - GB
                - ID
                - IT
                - JP
                - MX
                - MY
                - NL
                - PH
                - PL
                - PT
                - SG
                - TH
                - US
                - VN
              type: string
            - type: 'null'
        limit:
          anyOf:
            - default: 20
              description: >-
                Maximum items per page, not a guaranteed result count.
                Last-7-days requires 5-100; other boards allow 1-100.
              maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
        page:
          anyOf:
            - default: 1
              description: >-
                Page number. Monthly requires page times limit <= 100;
                last-7-days allows 1-5; Douyin and Bilibili require 1.
              maximum: 1000
              minimum: 1
              type: integer
            - type: 'null'
        period_value:
          anyOf:
            - description: >-
                Month in YYYY-MM format; required for the monthly board and
                forbidden for all other boards.
              maxLength: 32
              pattern: \S
              type: string
            - type: 'null'
        platform:
          description: Platform of the ranking; must match ranking_key.
          enum:
            - tiktok
            - douyin
            - bilibili
          type: string
        ranking_key:
          description: >-
            Ranking identity, including its metric and period; selects one board
            and cannot fall back to a different board.
          enum:
            - tiktok_shop.creator_gmv.monthly
            - tiktok_shop.creator_gmv.last7days
            - douyin.hot_accounts.24h
            - bilibili.follower_growth
          type: string
      required:
        - platform
        - ranking_key
      type: object
    creators.get_rankings_response.11_Result:
      allOf:
        - $ref: >-
            #/components/schemas/creators.get_rankings_response.5_CreatorRankingResult
        - allOf:
            - properties:
                items:
                  minItems: 1
                  minProperties: 1
                  not:
                    type: 'null'
                  pattern: \S
              required:
                - items
              type: object
    creators.get_rankings_error.1_ErrorDetail:
      additionalProperties: false
      else:
        properties:
          retryable:
            const: false
      if:
        properties:
          retry_hint:
            const: after_delay
      properties:
        code:
          enum:
            - invalid_request
            - invalid_input
            - unsupported_route
            - unsupported_capability
            - unsupported_identity
            - provider_rejected_input
            - invalid_cost_mode
            - cost_quote_payment_unsupported
            - cost_quote_unsupported
            - unpriced_request_value
            - missing_api_key
            - invalid_api_key
            - api_key_disabled
            - expired_api_key
            - unauthorized
            - forbidden
            - user_disabled
            - ip_not_allowed
            - api_key_access_denied
            - estimated_price_exceeds_max_price
            - insufficient_api_key_balance
            - insufficient_wallet_balance
            - task_not_found
            - endpoint_not_found
            - request_in_progress
            - request_already_completed
            - idempotency_conflict
            - request_id_conflict
            - request_too_large
            - method_not_allowed
            - rate_limit_exceeded
            - internal_error
            - service_unavailable
          type: string
        message:
          type: string
        param:
          type: string
        problems:
          items:
            type: string
          type: array
        request_id:
          minLength: 1
          type: string
        retry_hint:
          enum:
            - never
            - after_delay
            - reconcile_first
          type: string
        retryable:
          type: boolean
        similar_tasks:
          items:
            type: string
          type: array
        task_id:
          type: string
      required:
        - code
        - message
        - request_id
        - retryable
        - retry_hint
      then:
        properties:
          retryable:
            const: true
      type: object
    creators.get_rankings_response.5_CreatorRankingResult:
      additionalProperties: false
      properties:
        has_more:
          anyOf:
            - type: boolean
            - type: 'null'
        items:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/creators.get_rankings_response.3_CreatorRankedItem
              type: array
            - type: 'null'
        page:
          minimum: 1
          type: integer
        page_size:
          maximum: 100
          minimum: 1
          type: integer
        ranking:
          $ref: '#/components/schemas/creators.get_rankings_response.4_CreatorRanking'
        total:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
      required:
        - ranking
        - items
        - page
        - page_size
        - total
        - has_more
      type: object
    creators.get_rankings_response.3_CreatorRankedItem:
      additionalProperties: false
      properties:
        creator:
          $ref: '#/components/schemas/creators.get_rankings_response.6_CreatorSummary'
        metric_value:
          anyOf:
            - $ref: >-
                #/components/schemas/creators.get_rankings_response.0_CreatorCommerceMetric
            - type: 'null'
        native_rank:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
        position:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
      required:
        - creator
        - position
        - native_rank
        - metric_value
      type: object
    creators.get_rankings_response.4_CreatorRanking:
      additionalProperties: false
      properties:
        direction:
          anyOf:
            - enum:
                - asc
                - desc
              type: string
            - type: 'null'
        market:
          anyOf:
            - type: string
            - type: 'null'
        metric:
          anyOf:
            - enum:
                - gmv
                - follower_growth
              type: string
            - type: 'null'
        native_category:
          anyOf:
            - type: string
            - type: 'null'
        ranking_key:
          enum:
            - tiktok_shop.creator_gmv.monthly
            - tiktok_shop.creator_gmv.last7days
            - douyin.hot_accounts.24h
            - bilibili.follower_growth
          type: string
        window:
          $ref: '#/components/schemas/creators.get_rankings_response.7_CreatorWindow'
      required:
        - ranking_key
        - market
        - window
        - metric
        - direction
        - native_category
      type: object
    creators.get_rankings_response.6_CreatorSummary:
      additionalProperties: false
      properties:
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
        display_name:
          anyOf:
            - type: string
            - type: 'null'
        follower_count:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
        identity:
          $ref: >-
            #/components/schemas/creators.get_rankings_response.1_CreatorIdentity
      required:
        - identity
        - display_name
        - avatar_url
        - follower_count
      type: object
    creators.get_rankings_response.0_CreatorCommerceMetric:
      additionalProperties: false
      allOf:
        - if:
            properties:
              name:
                enum:
                  - gmv
            required:
              - name
          then:
            properties:
              unit:
                enum:
                  - currency
            required:
              - unit
        - if:
            not:
              properties:
                name:
                  enum:
                    - gmv
              required:
                - name
          then:
            properties:
              unit:
                enum:
                  - count
            required:
              - unit
        - if:
            not:
              properties:
                name:
                  enum:
                    - follower_growth
              required:
                - name
          then:
            properties:
              value:
                anyOf:
                  - minimum: 0
                  - type: 'null'
      oneOf:
        - properties:
            amount:
              type: 'null'
            unit:
              const: count
            value:
              type: number
        - properties:
            amount:
              type: object
            unit:
              const: currency
            value:
              type: 'null'
      properties:
        amount:
          anyOf:
            - $ref: >-
                #/components/schemas/creators.get_rankings_response.2_CreatorMoney
            - type: 'null'
        name:
          enum:
            - gmv
            - sales_count
            - product_count
            - follower_growth
          type: string
        scope:
          enum:
            - creator
            - product
          type: string
        unit:
          enum:
            - count
            - currency
          type: string
        value:
          anyOf:
            - type: number
            - type: 'null'
        window:
          $ref: '#/components/schemas/creators.get_rankings_response.7_CreatorWindow'
      required:
        - name
        - scope
        - value
        - amount
        - unit
        - window
      type: object
    creators.get_rankings_response.7_CreatorWindow:
      additionalProperties: false
      properties:
        days:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
        end:
          anyOf:
            - type: string
            - type: 'null'
        kind:
          enum:
            - snapshot
            - rolling
            - calendar
            - recent_posts
            - lifetime
            - unknown
          type: string
        label:
          anyOf:
            - type: string
            - type: 'null'
        start:
          anyOf:
            - type: string
            - type: 'null'
        timezone:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - kind
        - start
        - end
        - days
        - timezone
        - label
      type: object
    creators.get_rankings_response.1_CreatorIdentity:
      additionalProperties: false
      allOf:
        - else:
            properties:
              id_namespace:
                type: 'null'
          if:
            properties:
              native_id:
                type: string
          then:
            properties:
              id_namespace:
                minLength: 1
                type: string
      anyOf:
        - properties:
            native_id:
              minLength: 1
              type: string
        - properties:
            handle:
              minLength: 1
              type: string
        - properties:
            profile_url:
              minLength: 1
              type: string
      properties:
        handle:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        id_namespace:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        native_id:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        platform:
          enum:
            - instagram
            - tiktok
            - youtube
            - twitter
            - twitch
            - onlyfans
            - douyin
            - xiaohongshu
            - bilibili
            - facebook
            - snapchat
            - pinterest
            - linkedin
            - discord
          type: string
        profile_url:
          anyOf:
            - format: uri
              type: string
            - type: 'null'
      required:
        - platform
        - native_id
        - id_namespace
        - handle
        - profile_url
      type: object
    creators.get_rankings_response.2_CreatorMoney:
      additionalProperties: false
      properties:
        amount:
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
          type: string
        currency:
          pattern: ^[A-Z]{3}$
          type: string
      required:
        - amount
        - currency
      type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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