Skip to content

API

Everything on Profilestr is available as JSON at https://profilestr.com. No key needed, and CORS is open, so you can call it from a browser. Please cache what you can.

Relays

Built from the relay lists of every indexed profile: their NIP-65 list (kind 10002) where they've published one, otherwise the relay map in their follow list. Each relay is checked live (a WebSocket connect plus its NIP-11 document); results are cached for 15 minutes.

GET/api/relays

Relays ranked by how many profiles use them, with live status and NIP-11 details. Also returns onlineRelays and offlineRelays: the full lists of relay URLs our background checker last saw up or down, most-used first (not affected by the filters or paging).

status
all, online or offline. Default all.
sort
users, activeUsers or latency. Default users.
minUsers
Leave out relays named by fewer profiles. Default 2.
q
Only relays whose URL contains this text.
limit
1 to 500. Default 100.
offset
For paging. Default 0.
probe
false skips the live check and returns counts only (much faster).
statusLists
false leaves out onlineRelays and offlineRelays.
GET /api/relays?status=online&limit=10

GET/api/relays/check?url=wss://…

Live status, latency and the NIP-11 document for a single relay, plus how many indexed profiles use it.

url
The relay's wss:// address. Required.
GET /api/relays/check?url=wss://nos.lol

GET/api/relays/history?url=wss://…

Uptime and latency history for a single relay from our background checker, which connects to each relay about once an hour. Returns uptime for the last 24 hours, 7, 30 and 90 days, one row per day, and every check from the last 48 hours. A relay that answers but needs payment or login counts as up.

url
The relay's wss:// address. Required.
days
1 to 90. How many days of daily rows to return. Default 90.
GET /api/relays/history?url=wss://nos.lol&days=30

GET/api/relays/users?url=wss://…

Indexed profiles that list a relay in their NIP-65 relay list (or the relay map in their follow list), with whether they read from it, write to it or both. Rebuilt hourly.

url
The relay's wss:// address. Required.
marker
all, read or write. Default all. read and write include profiles that use it for both.
active
true keeps only profiles active in the last 30 days.
sort
followers or recent. Default followers.
limit
1 to 100. Default 50.
offset
For paging. Default 0.
GET /api/relays/users?url=wss://nos.lol&active=true&limit=10

GET/api/profile/:pubkey/relays

One profile's relays, with read/write markers and where the list came from (nip65 or kind3).

pubkey
npub or 64-character hex key.
probe
true adds online and latencyMs for each relay.
GET /api/profile/npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m/relays?probe=true

Profiles

Profile metadata and activity counts for every indexed account.

GET/api/profile/:pubkey

A full profile, including the combined trust score and its breakdown.

pubkey
npub or 64-character hex key.
GET /api/profile/npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m

GET/api/users

Search and filter profiles.

name, displayName, about, nip05
Partial, case-insensitive matches.
pubkey
npub or hex key.
minFollowers, maxFollowers, minNotes, maxNotes, minZaps, maxZaps
Numeric ranges.
sortBy
followers, notes, zaps, created or updated. Default followers.
sortOrder
asc or desc. Default desc.
limit, offset
Limit 1 to 100, default 10.
GET /api/users?minFollowers=1000&limit=5

GET/api/users/:pubkey

One profile by npub or hex key.

pubkey
npub or 64-character hex key.
GET /api/users/npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m

GET/api/users/:displayName

Find profiles by name, ranked by relevance.

displayName
The name to look for. An npub or hex key also works.
limit
1 to 50. Default 10.
exact
true for exact matches only.
GET /api/users/fiatjaf?limit=3

GET/api/users/random

A random selection of profiles.

limit
1 to 50. Default 10.
includeNpub
true to add the npub to each profile.
GET /api/users/random?limit=3&includeNpub=true

POST/api/users/batch

Names, pictures and last-active times for up to 100 hex pubkeys at once. Keys we haven't indexed come back as null.

Body: { "pubkeys": ["82341f88…", "3bf0c63f…"] }

POST /api/users/batch

GET/api/stats

Totals and distributions across the whole index.

includeTopUsers, topUsersLimit
Add the most-followed profiles (up to 50).
GET /api/stats

GET/api/stats/history

Daily, weekly and monthly active profiles over time, from a snapshot the indexer saves once a day. Each row has the rolling counts as of its last day, the average daily active count across the period, the total indexed and its change since the previous period, and profile completion counts. Newest first.

period
day, week or month. Weeks start on Monday (UTC). Default day.
limit
How many periods, 1 to 365. Default 30.
GET /api/stats/history?period=week&limit=12

Follow and mute lists

Who a profile follows (their kind 3 list) and who they mute (kind 10000), newest saved version first. We keep earlier versions too, so you can see what changed and when.

GET/api/profile/:pubkey/follows

The accounts a profile follows, with names and pictures for the ones we've indexed, plus a summary of every saved version of the list.

pubkey
npub or 64-character hex key.
limit
1 to 1000. Default 100.
offset
For paging. Default 0.
details
false returns keys only, without names and pictures (faster).
GET /api/profile/npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m/follows?limit=5

GET/api/profile/:pubkey/mutes

The accounts, words and hashtags a profile mutes publicly. Private mutes are encrypted, so we can only say whether there are any (hasPrivate).

pubkey
npub or 64-character hex key.
limit
1 to 1000. Default 100.
offset
For paging. Default 0.
details
false returns keys only, without names and pictures (faster).
GET /api/profile/npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m/mutes?limit=5

GET/api/lists/:type/:id

One saved version of a list as the raw signed Nostr event. Version ids come from the versions array of the two endpoints above.

type
follows or mutes.
id
A version id.
GET /api/lists/follows/<version id>

AI agents

Agents can use the same data through our MCP server at https://profilestr.com/mcp (Streamable HTTP, no key). Its tools search profiles and fetch profiles, follow and mute lists, relays and network stats. Add it to your client as a remote MCP server:

{
  "mcpServers": {
    "profilestr": { "type": "http", "url": "https://profilestr.com/mcp" }
  }
}

Or from Claude Code:

claude mcp add --transport http profilestr https://profilestr.com/mcp

Agents that prefer plain HTTP can start from /llms.txt, a short map of the site and API, or /openapi.json.

Errors

Failed requests return a JSON body with an error message. 400 means a parameter was wrong (usually a malformed key), 404 means we haven't indexed that profile, and 500 means something broke on our side.