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"

import requests

response = requests.get(
    "https://www.metaculus.com/api/users/me/",
    headers={"Authorization": "Token YOUR_TOKEN"}
)
print(response.json())

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

Response

integer

User ID

string

Username

string

Email address (private)

string (datetime)

When the user registered

string

User bio in markdown

string

Personal website URL

boolean

Whether this is a bot account

boolean

Whether the user is Metaculus staff

boolean

Whether the user has admin privileges

string

Profile picture URL

string

Geographic location

string

Professional occupation

string

Twitter handle

string

LinkedIn profile URL

string

GitHub username

boolean

Whether to hide community predictions by default

boolean

Whether the user has completed onboarding

number

Default forecast auto-withdrawal percentage

string

UI theme preference: light, dark, or auto

string

Preferred language code

string

API access tier level

array

List of email notification types the user has unsubscribed from

array

Previous usernames

object

Additional user metadata

Get User Profile

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

import requests

response = requests.get(
    "https://www.metaculus.com/api/users/12345/",
    headers={"Authorization": "Token YOUR_TOKEN"}
)
print(response.json())

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

Path Parameters

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"

import requests

response = requests.get(
    "https://www.metaculus.com/api/users/",
    headers={"Authorization": "Token YOUR_TOKEN"},
    params={"limit": 20}
)
print(response.json())

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

Query Parameters

integer

default:"20"

Number of users to return

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"
  }'

import requests

response = requests.patch(
    "https://www.metaculus.com/api/users/me/update/",
    headers={
        "Authorization": "Token YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "bio": "Updated bio",
        "website": "https://example.com",
        "location": "San Francisco, CA"
    }
)
print(response.json())

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

Request Body

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

string

User bio (supports markdown)

string

Personal website URL

string

Geographic location

string

Professional occupation

string

Twitter handle

string

LinkedIn profile URL

string

GitHub username

string

Profile picture URL

boolean

Hide community predictions by default

string

UI theme: light, dark, or auto

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"}'

import requests

response = requests.post(
    "https://www.metaculus.com/api/users/change-username/",
    headers={
        "Authorization": "Token YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={"username": "new_username"}
)
print(response.json())

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

Request Body

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"
  }'

import requests

response = requests.post(
    "https://www.metaculus.com/api/users/me/password/",
    headers={
        "Authorization": "Token YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "old_password": "current_password",
        "new_password": "new_secure_password"
    }
)
print(response.status_code)

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

Request Body

string

required

Current 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"

import requests

response = requests.get(
    "https://www.metaculus.com/api/users/me/bots/",
    headers={"Authorization": "Token YOUR_TOKEN"}
)
print(response.json())

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

Response

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"
  }'

import requests

response = requests.post(
    "https://www.metaculus.com/api/users/me/bots/create/",
    headers={
        "Authorization": "Token YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "username": "my_bot",
        "bio": "Automated forecasting bot"
    }
)
bot = response.json()
print(f"Created bot: {bot['username']} (ID: {bot['id']})")

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

Request Body

string

required

Bot username

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"

import requests

response = requests.get(
    "https://www.metaculus.com/api/users/me/bots/12345/token/",
    headers={"Authorization": "Token YOUR_TOKEN"}
)
token_data = response.json()
print(f"Bot token: {token_data['token']}")

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

Path Parameters

integer

required

The bot’s user ID

Response

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"
  }'

import requests

response = requests.patch(
    "https://www.metaculus.com/api/users/me/bots/12345/update/",
    headers={
        "Authorization": "Token YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "bio": "Updated bot description",
        "website": "https://github.com/user/bot"
    }
)
print(response.json())

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

Path Parameters

integer

required

The bot’s user ID

Request Body

Same fields as user profile update, plus:

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

​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

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