---
title: "Reddit API Login"
method: POST
path: "/api/reddit/login"
tags: ["Auth"]
---

# Reddit API Login

`POST /api/reddit/login`

## Request

- Base URL: `https://api.redditapis.com`
- URL: `https://api.redditapis.com/api/reddit/login`
- Auth: HTTP bearer

Log in with a Reddit username + password (and TOTP secret for 2FA accounts) to obtain the session cookies used by the write, vote, profile, and DM endpoints. Cost: $0.012 per call.

## Request body

- object
  - `username` string, required: Reddit username or email
  - `password` string, required: Account password
  - `totp_secret` string: Base32 TOTP secret for accounts with 2FA enabled. Omit if 2FA is off.
  - `method` string: http (default) | browser. Use browser for the most compatible write-session cookies.
  - `proxy` union: Sticky IP for this account — match the proxy used for /api/reddit/login, and send it on every call for that account. Object { server, username?, password? } or a proxy URL string. A bare host:port is accepted and treated as http. Schemes: http, https, socks4, socks5, socks5h (browser-backed endpoints support http, https, socks5). Pinned across internal retries; omit to use our shared pool.
    - object
      - `server` string, required
      - `username` string
      - `password` string
    - string
  - `locale` string: BCP-47 tag for the browser context, e.g. de-DE. Match it to the proxy's country. Default en-US. Applies to the browser context: with method=browser always, and with the default method=http only if that login falls back to a browser (which it does when Reddit blocks the http transport before the login form).
  - `timezone` string: IANA zone for the browser context, e.g. Europe/Berlin. Match it to the proxy's country, or the account acts from your proxy's IP while reporting a New York clock. Casing and aliases are normalised (utc to UTC, europe/berlin to Europe/Berlin, GMT to UTC, Japan to Asia/Tokyo). A numeric offset such as +05:30 is not a timezone and is rejected. Default America/New_York. Applies to the browser context: with method=browser always, and with the default method=http only if that login falls back to a browser (which it does when Reddit blocks the http transport before the login form).

## Response `200`

Successful response.

- object

## Other responses

- `400`: Bad request — missing or invalid parameters.
- `401`: Missing Bearer token (no API key on the request), OR two-factor required/invalid. With no code the fix is to add your API key. With code TWO_FACTOR_REQUIRED, 2FA is enabled but no totp_secret was supplied; TWO_FACTOR_INVALID means the secret could not produce a code. All are statements about YOUR request and are safe to act on. Terminal: do not retry unchanged. (An invalid, as opposed to missing, token is a 403.)
- `402`: Your account balance does not cover this call, so nothing was charged and the request was not served. The response body is {"error":"Insufficient credits","top_up_url":"https://www.redditapis.com/dashboard/buy-credits","message":"..."}; error keeps that exact wording. This is a billing state, not a bad request: the same call succeeds once the balance is topped up, and retrying without topping up returns 402 again, which is why it carries Retry-After: 3600. Top up at the top_up_url, then call again at once; the header does not apply after a top-up. Read the remaining balance any time from GET /account/me, which is free and never returns this error. Distinct from the 402 on the monitoring endpoints, which is about plan entitlements rather than credits.
- `403`: Invalid Bearer token.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error.
- `502`: Reddit gave no reliable verdict on the credentials. Branch on the body `code`: UNKNOWN, UPSTREAM_ERROR and UPSTREAM_BLOCKED are our-side and transient, so retry (ideally with a different proxy IP) and these are NOT billed; CAPTCHA_REJECTED and CAPTCHA_SOLVER_FAILED are a login-captcha problem (usually the proxy IP's reCAPTCHA reputation), also NOT billed, retry with a different, ideally residential, IP; AUTH_FAILED is held here temporarily (Reddit blamed the credentials but currently returns the same message for correct ones) and is TERMINAL, so do not retry unchanged, check the credentials. UPSTREAM_ERROR carries Reddit's own reference in upstream_ref when it supplied one.

---

[API](https://skmtc.dev/redditapis/apis/redditapis-api.md) · [All operations](https://skmtc.dev/redditapis/apis/redditapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/redditapis/apis/redditapis-api/revisions/9696482dfe9b?raw)