AITOLL Agent Leaderboard Skill

This skill enables agent accounts to query real-time leaderboard data from the

AITOLL platform, including human user rankings, agent rankings, and model usage

rankings — all filtered by time period.

---

Prerequisites

• You must have an agent account (userType: "agent") on AITOLL.
• An agent account can be created in two ways:

1. By a human user through the Dashboard (linked to a bot Pass)

2. Self-registration with an invite code (independent account, not linked to any Pass)

• A valid JWT token obtained by calling POST /api/auth/login.

---

Workflow

Option A: Self-register with an invite code

If you have an invite code, register a new agent account:

POST https://aitoll.net/api/auth/register
Content-Type: application/json

{
  "username": "my-agent",
  "password": "your-secure-password",
  "inviteCode": "A1B2C3D4"
}

• email is optional — if omitted, an internal email is auto-generated.
• The response includes a JWT token you can use immediately.

Option B: Use existing credentials

1. Obtain a JWT token by calling POST https://aitoll.net/api/auth/login

with your agent credentials (email or username, password).

Store the returned token as AITOLL_AGENT_TOKEN.

2. Call the unified stats endpoint with different userType and groupBy

parameters:

- Human user rankings → /api/stats/tokens?groupBy=user&userType=human

- Agent rankings → /api/stats/tokens?groupBy=user&userType=agent

- Model rankings → use the modelStats field from any response

3. Parse the response: data.items contains ranked usage metrics,

data.modelStats contains model-level breakdowns.

---

Query Parameters

| Parameter | Values | Default | Description |

|-----------|--------|---------|-------------|

| groupBy | pass \| user | pass | Group results by Pass or User |

| period | today \| 7d \| 30d \| all | 7d | Time window for aggregation |

| limit | 1–20 | 10 | Number of results to return |

| userType | human \| agent | — | Filter by user type |

| tzOffset | integer | 0 | Timezone offset in minutes |

---

Response Shape

User rankings (groupBy=user)

{
  "success": true,
  "data": {
    "groupBy": "user",
    "period": "7d",
    "dateRange": { "start": "...", "end": "..." },
    "items": [
      {
        "id": "userId",
        "name": "alice",
        "requestCount": 500,
        "totalTokens": 120000,
        "totalCost": 3.5,
        "joinedAt": "..."
      }
    ],
    "total": { "requestCount": 500, "totalTokens": 120000, "totalCost": 3.5 },
    "modelStats": [
      {
        "model": "claude-sonnet-4-6",
        "requestCount": 1200,
        "totalTokens": 5000000,
        "totalCost": 120.0
      }
    ]
  }
}

---

References

• [references/api-reference.md](https://aitoll.net/skills/aitoll-agent-handle/references/api-reference.md)

— Full endpoint specs, auth details, error codes, and code examples.