---
title: "List Subreddits"
description: "Lists popular or newly created subreddits across Reddit.\n"
---

> Documentation Index
> Fetch the complete documentation index at: https://staging.threadapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

Path: ThreadAPI API › Reddit

`GET /v1/reddit/subreddits`

Lists popular or newly created subreddits across Reddit.

## Authentication

Requires one of the following:

- `bearerAuth`, http, header `Authorization`
- `apiKeyAuth`, apiKey, in header, header `x-api-key`

## Query parameters

- `sort` (`getSubreddits.query.sort`; string, optional) — Subreddit listing sort.
  - one of `"popular"`, `"new"`; default `"popular"`
- `limit` (`getSubreddits.query.limit`; integer, optional) — Number of items per page.
  - min 1; max 100; default `25`
- `after` (`getSubreddits.query.after`; string, optional) — Pagination cursor from the previous page's `after` field.
- `nsfw` (`getSubreddits.query.nsfw`; boolean, optional) — Include NSFW content (filtered out by default).
  - default `false`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://api.threadapi.dev/v1/reddit/subreddits \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://api.threadapi.dev/v1/reddit/subreddits';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.threadapi.dev/v1/reddit/subreddits"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Subreddit listing.

#### Example

```json
{
  "query": "string",
  "sort": "string",
  "count": 0,
  "items": [
    {
      "name": "string",
      "title": "string",
      "public_description": "string",
      "description": "string",
      "subscribers": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "over_18": true,
      "type": "string",
      "url": "string",
      "icon": "string",
      "rules": [
        {
          "kind": "string",
          "short_name": "string",
          "description": "string",
          "violation_reason": "string",
          "priority": 0,
          "created_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ],
  "after": "string",
  "filtered_nsfw": 0,
  "degraded": true
}
```

- `sort` (`getSubreddits.response.200.sort`; string, required)
- `count` (`getSubreddits.response.200.count`; integer, required)
- `items` (`getSubreddits.response.200.items`; array<object>, required)
  - `name` (`getSubreddits.response.200.items.name`; string, optional)
  - `title` (`getSubreddits.response.200.items.title`; string, optional)
  - `public_description` (`getSubreddits.response.200.items.public_description`; string, optional)
  - `description` (`getSubreddits.response.200.items.description`; string, optional)
  - `subscribers` (`getSubreddits.response.200.items.subscribers`; integer, optional)
  - `created_at` (`getSubreddits.response.200.items.created_at`; string, optional)
    - format `date-time`
  - `over_18` (`getSubreddits.response.200.items.over_18`; boolean, optional)
  - `type` (`getSubreddits.response.200.items.type`; string, optional)
  - `url` (`getSubreddits.response.200.items.url`; string, optional)
  - `icon` (`getSubreddits.response.200.items.icon`; string, optional)
  - `rules` (`getSubreddits.response.200.items.rules`; array<object>, optional)
    - `kind` (`getSubreddits.response.200.items.rules.kind`; string, optional)
    - `short_name` (`getSubreddits.response.200.items.rules.short_name`; string, optional)
    - `description` (`getSubreddits.response.200.items.rules.description`; string, optional)
    - `violation_reason` (`getSubreddits.response.200.items.rules.violation_reason`; string, optional)
    - `priority` (`getSubreddits.response.200.items.rules.priority`; integer, optional)
    - `created_at` (`getSubreddits.response.200.items.rules.created_at`; string, optional)
      - format `date-time`
- `filtered_nsfw` (`getSubreddits.response.200.filtered_nsfw`; integer, required)
- `query` (`getSubreddits.response.200.query`; string | null, optional)
- `after` (`getSubreddits.response.200.after`; string | null, optional)
- `degraded` (`getSubreddits.response.200.degraded`; boolean, optional)

### 400

Bad request (invalid parameter or unknown action)

#### Example

```json
{
  "error": "unauthorized: missing or invalid credentials",
  "error_code": "insufficient_credits"
}
```

One of:

- `ErrorResponse`
- `Error`

### 401

Missing or invalid API key or OAuth access token

#### Example

```json
{
  "error": "unauthorized: missing or invalid credentials",
  "error_code": "insufficient_credits"
}
```

One of:

- `ErrorResponse`
- `Error`

### 402

The account has no credits left (`insufficient_credits`).

#### Example

```json
{
  "error": {
    "code": "not_found",
    "message": "string",
    "retryable": true,
    "retry_after": 0
  }
}
```

- `error` (`getSubreddits.response.402.error`; object, required)
  - `code` (`getSubreddits.response.402.error.code`; string, required)
    - example `"not_found"`
  - `message` (`getSubreddits.response.402.error.message`; string, required)
  - `retryable` (`getSubreddits.response.402.error.retryable`; boolean, required)
  - `retry_after` (`getSubreddits.response.402.error.retry_after`; integer, optional) — Seconds to wait before retrying.

### 429

Rate limit or daily request quota exceeded

#### Example

```json
{
  "error": "unauthorized: missing or invalid credentials",
  "error_code": "insufficient_credits"
}
```

One of:

- `ErrorResponse`
- `Error`

### 503

A temporary problem reaching Reddit (`upstream_busy`, `upstream_timeout`, `upstream_error`). Retry shortly; nothing was billed.

#### Example

```json
{
  "error": {
    "code": "not_found",
    "message": "string",
    "retryable": true,
    "retry_after": 0
  }
}
```

- `error` (`getSubreddits.response.503.error`; object, required)
  - `code` (`getSubreddits.response.503.error.code`; string, required)
    - example `"not_found"`
  - `message` (`getSubreddits.response.503.error.message`; string, required)
  - `retryable` (`getSubreddits.response.503.error.retryable`; boolean, required)
  - `retry_after` (`getSubreddits.response.503.error.retry_after`; integer, optional) — Seconds to wait before retrying.


Source: https://staging.threadapi.dev/api/Reddit/getSubreddits/index.md