u/<username>, @<username>, or a Reddit profile URL. POST /search only validates and normalizes the identifier; it does not call a provider or consume credits.
Search types
The canonical type isusername. The aliases pseudonym, reddit, u, and user are normalized to username.
Endpoints and costs
Costs are in
core_search units. Authentication and the tools plan feature
are required even for free operations. Standalone routes retain their per-call
prices; use the ID-based flow below for a predictable total.
Recommended: profile first, navigation included
Start one synchronous lookup. It collects the profile only, always saves it, and returnsmeta.savedResult.id. No polling or background job is involved.
save: false does not disable persistence on this route.
operation: "lookup", data.profile, and the usual
query/meta wrapper. Read the saved profile later using
GET /tools/results/<id>. Use that same ID for navigation:
posts, comments, activity, communities. The account is
derived from the stored result; do not send value or type. Responses use
the section name as operation and include meta.resultId.
One lookup costs 1; all subsequent /browse calls for that ID cost 0.
This also applies to saved /all results. A saved /profile alone does not
include browsing: complete it with /feed (1 + 2 = 3), or start /lookup.
No new usage event is created by /browse. Free browsing is not a promise of
unlimited throughput or complete archives: provider limits still apply.
Each call verifies the creator and the API key that own the saved result.
An unknown, deleted, foreign, or non-Reddit result returns 404. A profile-only
result returns 409 RESULT_BROWSING_NOT_INCLUDED. Deleting the saved result
revokes browsing access, including access to cached pages.
Opaque pagination
Usedata.pagination.nextCursor unchanged for the next page:
nextCursor: null means no continuation is available. Cursors retain filters,
page size, and chronological direction and are bound to one result/section.
They are pagination state, not credentials. Do not combine a cursor with
options; malformed or mismatched cursors return 400 VALIDATION_ERROR.
For a first page, optional options accepts limit (1-100), sort (asc or
desc), after, before, subreddit, keywords, deletedOnly, nsfwOnly.
Omitting options inherits the original lookup filters and page size (25 by
default for /lookup). Supplying options starts a new filtered view with
defaults for omitted fields. Changing filters requires dropping the cursor.
An empty filtered page can still have a continuation; follow nextCursor.
Score ordering remains a standalone-route, within-page sort, not a global
historical ranking. Archive pagination is timestamp-based and best-effort,
not an exhaustive export guarantee for extremely high-volume accounts.
Reuse and persistence
Matching first pages and activity from a saved/all are reused directly.
Activity enrichment reuses the saved profile instead of resolving it again.
Missing sections are collected on demand; provider and browse responses are
cached in production. /browse does not rewrite the R2 snapshot: the saved
profile/all response remains unchanged. Later pages may reflect newer archive
data after cache expiry. Keep returned pages client-side when you need them
as part of an export. Reopening /lookup creates and charges a new lookup;
reuse the existing ID on refresh.
Search
Complete lookup
POST /all returns the first page of profile activity, up to 100 posts and 100 comments. It also returns community and deterministic activity summaries. Secondary provider failures appear in partialErrors when another source succeeds.
/browse pagination above. Standalone /posts
and /comments remain available at 1 per call; pass pagination.nextBefore
unchanged as before to load older pages:
after, before, deletedOnly, keywords, limit, nsfwOnly, sort, and subreddit. Date cursors accept ISO dates or Unix timestamps. sort accepts asc, desc, or score.
Threads
Load a known post’s archived comments. The post must belong to the queried username. Reddit fullnames such ast3_abc123 and t1_def456 are accepted and normalized.
Sources and cache
Arctic Shift is queried first. PullPush supplements incomplete or unavailable pages; records are deduplicated by ID. Official profile and author-avatar requests require server-side OAuth configuration; the unauthenticated Reddit profile endpoint is not used. Profile-report and archive sources remain available without Reddit OAuth. Avatars, banners and other account fields are nullable when unavailable; archived activity can still be returned. Public errors andpartialErrors expose stable codes, generic messages and
capability names, not upstream URLs or diagnostic messages. Secondary failures
can produce a successful but partial response.
In production, recent content and browse responses are cached for 15 minutes,
current profiles for 30 minutes, date-bounded history and community metadata
for 6 hours, and threads for 1 hour. Provider caching is disabled outside
production. Cache hits do not change route pricing. Stored results are not
the provider cache and remain accessible until deleted.