Skip to content

api

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

api

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Arctic Shift API

An API for querying reddit data.

No uptime or performance guarantees :)

Base URL: https://arctic-shift.photon-reddit.com

Status page: https://status.arctic-shift.photon-reddit.com

Search UI: https://arctic-shift.photon-reddit.com/search

ID lookup

Retrieve things based on their ID

Parameter Type Default Notes
ids ID[] Comma separated list. Limit: 500
md2html boolean false If true, adds auto generated selftext_html/body_html field
fields string Comma separated list of fields to return (more info)

Posts and comments

Search

Common parameters:

Parameter Type Default Notes
author string
subreddit string
author_flair_text string (keyword search) for limitations see title or body below
after Date Time when thing was posted
before Date Time when thing was posted
limit int (1 - 100) | "auto" 25 With "auto" between 100 and 1000 results are returned, depending on the capacity of the server
sort asc | desc Results are sorted by created_utc
md2html boolean false If true, adds auto generated selftext_html/body_html field
fields string Comma separated list of fields to return (more info)

Post search parameters:

Parameter Type Default Notes
crosspost_parent_id ID
over_18 boolean
spoiler boolean
title string (keyword search) Only in use with author or subreddit parameter (not supported with very active users or subreddits)
selftext string (keyword search) ...
link_flair_text string (keyword search) ...
query string Search in both title and selftext (keyword search) ...
url string prefix match, example: https://www.youtube.com/xyz will return https://www.youtube.com/xyz?p=abc or also https://www.youtube.com/xyz?t=15s
url_exact boolean false if true, url queries will only return exact matches

Comment search parameters:

Parameter Type Default Notes
body string (keyword search) Only in use with author, subreddit, link_id or parent_id parameter (not supported with very active users or subreddits)
link_id ID ID of post
parent_id ID | empty Parent comment id. Empty means top level comment

Comments tree

Retrieve comments in a tree structure, similar to how they are displayed on reddit.

If limit is exceeded, comments are collapsed. Collapsed comments use "kind": "more" and have a children field containing the IDs of the comments that are collapsed, the same way the reddit API does it. start_breadth and start_depth decrease by 1 for each depth level. Comments outside the current breadth or depth are collapsed.

Parameter Type Default Notes
link_id ID ID of post (required)
parent_id ID If unset, all comments under the post are returned
limit int (1 - 25000) 50 Something like 9999 returns all comments
start_breadth int (>= 0) 4 For comment collapsing
start_depth int (>= 0) 4 For comment collapsing
md2html boolean false If true, adds auto generated body_html field

Aggregations

Aggregate results based on date, author or subreddit.

All filtering related parameters from the search endpoints are supported.

Very active users or subreddits have a high chance of timing out.

Parameter Type Default Notes
aggregate created_utc | author | subreddit
frequency string (interval) Required with aggregate=created_utc
limit int (>= 1) | empty empty empty means no limit (limit=)
min_count int (>= 0) Not used with aggregate=created_utc
sort asc | desc asc with aggregate=created_utc, otherwise desc

Subreddits

Search

Note: List of subreddits and their data is only updated infrequently. Aggregate _meta data is updated more frequently.

Parameter Type Default Note
subreddit string
subreddit_prefix string
after Date Subreddit creation date
before Date Subreddit creation date
min_subscribers int
max_subscribers int
over18 boolean nsfw
limit int (1 - 1000) 25
sort asc | desc desc
sort_type created_utc | subscribers | subreddit subscribers
fields Comma separated list of fields to return (more info)

Rules

Retrieve the rules of a subreddit.

Parameter Type Default Notes
subreddits string[] Comma separated list of subreddit names. Limit: 1000

Wikis

Retrieve the wiki pages of a subreddit.

Parameter Type Default Notes
paths string[] Comma separated list of wiki pages. Limit: 100
subreddit string Return all wiki pages of a subreddit
limit int 100 Number of wiki pages to return. Max: 100

Retrieve the paths of all wiki pages of a subreddit.

Parameter Type Default Notes
subreddit string Return all wiki pages of a subreddit

Users

Search

Note: This is endpoint only contains aggregate data of user names, ids, number of posts/comments, earliest/latest posts/comments, karma, etc. It is only updated infrequently. _meta data is updated more frequently. Ids might be null if the user hasn't been active in recent years.

Parameter Type Default Note
author string
author_prefix string
min_num_posts int
min_num_comments int
active_since Date Date of first post or comment
min_karma int
limit int (1 - 1000) 25
sort asc | desc desc
sort_type author | total_karma total_karma Karma is the sum of post/comment scores

Interactions

Note: For very active users (especially bots), this has a high chance of timing out. In that case, try narrowing the time range using the after and before parameters.

User to user interactions

Aggregates number of interactions between users.

  • /api/users/interactions/users/list

Lists all individual interactions between users.

As an interactions counts:

  • author commented under a post
  • author commented under a comment
  • someone replied to author's post
  • someone replied to author's comment
Parameter Type Default Notes
author string required
subreddit string
after Date
before Date
min_count int (>= 0) Minimum number of interactions
limit int (>= 1) | empty 100 empty means no limit (limit=)

User to subreddit interactions

  • /api/users/interactions/subreddits

See in which subreddits a user has been active. Similar to the above /api/posts/search/aggregate and /api/comments/search/aggregate endpoints, but both are combined into one, with weighting and limiting options.

Parameter Type Default Notes
author string required
weight_posts float 1.0
weight_comments float 1.0
before Date
after Date
min_count int (>= 0) Minimum number of interactions
limit int (>= 1) | empty 100 empty means no limit (limit=)

Aggregate flairs

Aggregates all author_flair_text values of a user and groups them by subreddit.

Parameter Type Default Notes
author string required

Short links

Retrieve the full link of a short link.

Parameter Type Default Notes
paths string[] Comma separated list of paths (case sensitive). Max: 1000

Time series

Retrieve aggregated data over time. Data might not be 100% accurate, and might take a few hours or days to fully update.

Parameter Type Default Notes
key string Time series type or category. See below for available values
precision string One of year, quarter, month, week, day, hour, minute
after Date Start date. If not set, the earliest date of the data is used
before Date End date. If not set, the latest date of the data is used

Available keys:

  • global/posts/count, global/comments/count - Number of posts and comments across all of reddit
  • global/posts/sum_score, global/comments/sum_score - Sum of all upvotes
  • global/posts/sum_retrieved_after_seconds, global/comments/sum_retrieved_after_seconds - Sum of the time between the creation of post/comment and the time it was archived
  • r/<subreddit>/posts/count, r/<subreddit>/comments/count - Number of posts and comments in a subreddit
  • r/<subreddit>/posts/sum_score, r/<subreddit>/comments/sum_score - Sum of all upvotes in a subreddit
  • r/<subreddit>/subscribers - Number of subscribers in a subreddit

Data type notes

Selectable fields

By only selecting the fields you need, you can potentially reduce the response time and size.

Both posts & comments: author, author_fullname, author_flair_text, created_utc, distinguished, id, retrieved_on, subreddit, subreddit_id, score
Posts: crosspost_parent, link_flair_text, num_comments, over_18, post_hint, selftext, spoiler, title, url
Comments: body, link_id, parent_id
Subreddits: created_utc, description, public_description, display_name, id, over18, retrieved_on, subscribers, title, (and _meta fields)

Boolean

True values: true, 1, yes, y
False values: false, 0, no, n

ID

Base 36 encoded number. Can optionally start with a t3_/t1_ prefix for posts/comments. The ID is part of the link to a post/comment. (reddit.com/.../comments/<post_id>/.../<comment_id>).

Example valid IDs: sphocx, t3_sphocx, dppum98, t1_dppum98

Author and subreddit

If you include the u/ or r/ prefix, it will be ignored.

Date

Dates can be specified in the following formats:

  • Epoch time in seconds
  • Epoch time in milliseconds
  • ISO 8601 (partial)
    • 2020-01-01T00:00:00.000Z
    • 2020-01-01 00:00:00
    • 2020-01-01
  • Offset from current time (e.g. 1year, 3m, 2d, 1hour, 5min or 10s)

Full text search / Keyword search

This section is now out of date! Available search features might change and are not guaranteed

Currently: when searching posts: simply keyword search only (fast), when searching comments: postgres FTS features (slow)

For details, see here, specifically the websearch_to_tsquery function.

But in short:

  • Word1 Word2 searches for Word1 and Word2, regardless of order
  • "Word1 Word2" searches for Word1 followed by Word2, possibly with other words in between
  • Word1 OR Word2 searches for Word1 or Word2
  • Word1 -Word2 searches for Word1 but not Word2

Other notes

Rate limiting

If you're a normal user and only make a couple requests per second, you have nothing to worry about.

But if you make excessive requests, you might get rate limited. Rate limits are calculated dynamically based on server load and request complexity. If you receive a 429 rate limit error code, you have to wait until your limits reset. You can use the X-RateLimit-Reset (seconds until reset) or X-RateLimit-Reset-At (timestamp of next reset) headers.

Remember, this is a free service, so be considerate. If you want to process massive amounts of data, use the monthly dumps instead.

Query timeout

If you receive the message "Query timed out", you probably used a parameter combination that I haven't optimized. Try reducing the limit parameter or use a more specific filter (after, before, subreddit, author).

This usually happens with body, selftext or title parameters.

Sometimes the database needs to warm up, so if you try again a second time, it might work.

Upvotes count and number of comments

After roughly 36 hours, all data is updated and should then be the same as that released in .zst dumps. Before that, score, num_comments, etc. will be 1 or 0, since data is archived initially the moment it was posted.