Leaderboards

The Leaderboards API lets you create and query custom creator leaderboards with configurable scoring weights. Use it to power Aura Boards, internal rankings, or external-facing creator competitions.

Create a leaderboard

POST /v1/leaderboards

Request body

{
  "name": "My Campaign Leaderboard",
  "community_id": "com_abc123",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "weights": {
    "content_volume": 0.3,
    "engagement": 0.4,
    "brand_relevance": 0.2,
    "smart_followers": 0.1
  },
  "platform_filter": ["tiktok", "x"],
  "visibility": "public"
}

Parameters

Field	Type	Description
name	string	Display name for the leaderboard
community_id	string	Your Community ID
start_date	string	ISO 8601 date
end_date	string	ISO 8601 date
weights	object	Scoring weights. Must sum to 1.0
platform_filter	array	Platforms to include in scoring
visibility	string	public or private

Scoring weight options

Weight key	What it measures
content_volume	Number of qualifying posts
engagement	Total engagement (likes, comments, shares, views)
brand_relevance	AI-assessed relevance to your brand/brief
smart_followers	Influence-weighted follower count
quality_score	Creator's Airaa Quality Score

Get leaderboard rankings

GET /v1/leaderboards/{id}/rankings

Returns the current ranked list for the leaderboard.

Example response

{
  "data": {
    "leaderboard_id": "lb_abc123",
    "updated_at": "2026-05-08T14:22:00Z",
    "rankings": [
      {
        "rank": 1,
        "contributor_id": "ctr_abc123",
        "handle": "@creatorhandle",
        "score": 947.2,
        "content_count": 18,
        "total_engagement": 284000
      },
      {
        "rank": 2,
        "contributor_id": "ctr_def456",
        "handle": "@another",
        "score": 831.6,
        "content_count": 14,
        "total_engagement": 196000
      }
    ]
  }
}

List leaderboards

GET /v1/leaderboards

Returns all leaderboards for your organization.

Query parameters

Parameter	Type	Description
community_id	string	Filter by Community
status	string	active, ended, or all. Default: all
limit	integer	Results per page. Default: 20