Users

Overview

The Users endpoints provide access to public user profiles, allow users to manage their own accounts, and enable bot management. User profiles include forecasting statistics, bio information, and social links.

Get Current User

curl -X GET "https://www.metaculus.com/api/users/me/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/users/me/ Retrieve the authenticated user’s complete profile, including private information.

Response

integer

User ID

username

string

Username

string

Email address (private)

date_joined

string (datetime)

When the user registered

bio

string

User bio in markdown

website

string

Personal website URL

is_bot

boolean

Whether this is a bot account

is_staff

boolean

Whether the user is Metaculus staff

is_superuser

boolean

Whether the user has admin privileges

profile_picture

string

Profile picture URL

location

string

Geographic location

occupation

string

Professional occupation

twitter

string

Twitter handle

string

LinkedIn profile URL

github

string

GitHub username

hide_community_prediction

boolean

Whether to hide community predictions by default

is_onboarding_complete

boolean

Whether the user has completed onboarding

prediction_expiration_percent

number

Default forecast auto-withdrawal percentage

app_theme

string

UI theme preference: light, dark, or auto

language

string

Preferred language code

api_access_tier

string

API access tier level

unsubscribed_mailing_tags

array

List of email notification types the user has unsubscribed from

formerly_known_as

array

Previous usernames

metadata

object

Additional user metadata

Get User Profile

curl -X GET "https://www.metaculus.com/api/users/12345/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/users/{userId}/ Retrieve a public user profile.

Path Parameters

userId

integer

required

The user ID

Response

Returns the same fields as /api/users/me/ but excludes private information:

Email address
Unsubscribed mailing tags
Private metadata fields

List Users

curl -X GET "https://www.metaculus.com/api/users/?limit=20" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/users/ Retrieve a paginated list of user profiles.

Query Parameters

limit

integer

default:"20"

Number of users to return

offset

integer

default:"0"

Pagination offset

Update Profile

curl -X PATCH "https://www.metaculus.com/api/users/me/update/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Updated bio",
    "website": "https://example.com",
    "location": "San Francisco, CA"
  }'

PATCH /api/users/me/update/ Update the authenticated user’s profile.

Request Body

All fields are optional. Only include fields you want to update.

bio

string

User bio (supports markdown)

website

string

Personal website URL

location

string

Geographic location

occupation

string

Professional occupation

twitter

string

Twitter handle

string

LinkedIn profile URL

github

string

GitHub username

profile_picture

string

Profile picture URL

hide_community_prediction

boolean

Hide community predictions by default

app_theme

string

UI theme: light, dark, or auto

language

string

Preferred language code (e.g., “en”, “es”)

Change Username

curl -X POST "https://www.metaculus.com/api/users/change-username/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "new_username"}'

POST /api/users/change-username/ Change the authenticated user’s username.

Request Body

username

string

required

New username. Must be unique and meet format requirements.

Username Change Restrictions

Can only change username once every 180 days
Username must be 1-30 characters
Can only contain letters, numbers, and @/./+/-/_ characters
Cannot be a reserved username (e.g., “admin”, “moderator”)

Change Password

curl -X POST "https://www.metaculus.com/api/users/me/password/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "current_password",
    "new_password": "new_secure_password"
  }'

POST /api/users/me/password/ Change the authenticated user’s password.

Request Body

old_password

string

required

Current password

new_password

string

required

New password (must meet security requirements)

Bot Management

List My Bots

curl -X GET "https://www.metaculus.com/api/users/me/bots/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/users/me/bots/ Retrieve all bots created by the authenticated user.

Response

results

array

Array of bot user objects

Create Bot

curl -X POST "https://www.metaculus.com/api/users/me/bots/create/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my_bot",
    "bio": "Automated forecasting bot"
  }'

POST /api/users/me/bots/create/ Create a new bot account.

Request Body

username

string

required

Bot username

bio

string

Bot description

Response

Returns the created bot user object.

Get Bot Token

curl -X GET "https://www.metaculus.com/api/users/me/bots/12345/token/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/users/me/bots/{botId}/token/ Retrieve or generate an API token for a bot.

Path Parameters

botId

integer

required

The bot’s user ID

Response

token

string

The bot’s API authentication token

Store Bot Tokens SecurelyBot tokens provide full API access. Store them securely and never commit them to version control.

Update Bot Profile

curl -X PATCH "https://www.metaculus.com/api/users/me/bots/12345/update/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Updated bot description",
    "website": "https://github.com/user/bot"
  }'

PATCH /api/users/me/bots/{botId}/update/ Update a bot’s profile information.

Path Parameters

botId

integer

required

The bot’s user ID

Request Body

Same fields as user profile update, plus:

username

string

Update bot username (bots can change username without time restrictions)

Example: Complete Bot Setup

import requests

# Step 1: Create a bot
response = requests.post(
    "https://www.metaculus.com/api/users/me/bots/create/",
    headers={"Authorization": "Token YOUR_USER_TOKEN"},
    json={
        "username": "my_forecasting_bot",
        "bio": "Automated forecasting using ML models",
        "website": "https://github.com/user/forecasting-bot"
    }
)
bot = response.json()
bot_id = bot["id"]

# Step 2: Get bot token
response = requests.get(
    f"https://www.metaculus.com/api/users/me/bots/{bot_id}/token/",
    headers={"Authorization": "Token YOUR_USER_TOKEN"}
)
bot_token = response.json()["token"]

print(f"Bot created! Use this token for API calls: {bot_token}")

# Step 3: Use bot token to submit forecasts
response = requests.post(
    "https://www.metaculus.com/api/questions/forecast/",
    headers={"Authorization": f"Token {bot_token}"},
    json=[{"question": 1, "probability_yes": 0.75}]
)

print(f"Forecast submitted: {response.status_code}")

Getting Started

Endpoints

Examples

Overview

Get Current User

Response

Get User Profile

Path Parameters

Response

List Users

Query Parameters

Update Profile

Request Body

Change Username

Request Body

Change Password

Request Body

Bot Management

List My Bots

Response

Create Bot

Request Body

Response

Get Bot Token

Path Parameters

Response

Update Bot Profile

Path Parameters

Request Body

Example: Complete Bot Setup

Build docs developers (and LLMs) love

Getting Started

Endpoints

Examples

​Overview

​Get Current User

​Response

​Get User Profile

​Path Parameters

​Response

​List Users

​Query Parameters

​Update Profile

​Request Body

​Change Username

​Request Body

​Change Password

​Request Body

​Bot Management

​List My Bots

​Response

​Create Bot

​Request Body

​Response

​Get Bot Token

​Path Parameters

​Response

​Update Bot Profile

​Path Parameters

​Request Body

​Example: Complete Bot Setup

Build docs developers (and LLMs) love

Overview

Get Current User

Response

Get User Profile

Path Parameters

Response

List Users

Query Parameters

Update Profile

Request Body

Change Username

Request Body

Change Password

Request Body

Bot Management

List My Bots

Response

Create Bot

Request Body

Response

Get Bot Token

Path Parameters

Response

Update Bot Profile

Path Parameters

Request Body

Example: Complete Bot Setup