Free Bluesky API: keys, limits and tested examples
Public reads need no Bluesky password. Use the public AppView for direct data, or the free Bluesky.bot tools API for a combined answer.
By The Bluesky.bot team
- Published:
- Updated:
- Reviewed:
Do you need a key?
For many public profile, feed and post reads, no: Bluesky operates a public AppView at public.api.bsky.app. It is one service in the AT Protocol, not every API. Writing a post needs account authorization and normally goes through that account’s PDS. Our tools API does not post, follow or delete anything.
Use Bluesky directly when a single XRPC method answers your question. A combined identity check is different: a handle can involve DNS, HTTPS, the DID document and an AppView answer. Our tools collect those observations and explain disagreements. A free creator token raises quotas; anonymous public tools do not need one.
What each endpoint answers
This table comes from the executing tool registry. Its cost is a quota weight, not money or a promise about an exact number of upstream requests. Caches can avoid an upstream request entirely; an identity check can need several.
| Tool | Endpoint | HTTP cache | Quota cost |
|---|---|---|---|
| Declared automation checker See the automation signals an account makes public. | GET /api/v1/tools/bot-checker | 60 seconds | 3 unit(s) |
| DID finder Get the DID behind any Bluesky handle. | GET /api/v1/tools/did-finder | 60 seconds | 1 unit(s) |
| Handle finder (DID to handle) Find the handle behind a DID. | GET /api/v1/tools/handle-finder | 60 seconds | 1 unit(s) |
| Bluesky whois Everything public about a handle or a DID. | GET /api/v1/tools/whois | 60 seconds | 3 unit(s) |
| Account age checker See when any account joined Bluesky. | GET /api/v1/tools/account-age | 60 seconds | 1 unit(s) |
| AT-URI converter Turn a bsky.app link into an at:// URI, and back. | GET /api/v1/tools/at-uri-converter | 60 seconds | 1 unit(s) |
| TID decoder Read the date hidden in a record key. | GET /api/v1/tools/tid-decoder | 1 year | 1 unit(s) |
| Post character counter Count your post the way Bluesky does. | GET /api/v1/tools/character-counter | 1 year | 1 unit(s) |
| Rich text facet builder Mentions, links and hashtags with their byte offsets. | GET /api/v1/tools/facet-builder | Not cached | Depends on the request |
| Custom domain handle checker Find out why your handle is invalid, and how to fix it. | GET /api/v1/tools/custom-handle-checker | Not cached | 2 unit(s) |
| Handle availability checker Is your name free on Bluesky? | GET /api/v1/tools/handle-availability | Not cached | 1 unit(s) |
| PLC history viewer Every handle change, server move and key change of an account. | GET /api/v1/tools/plc-history | 5 minutes | 2 unit(s) |
| Starter pack analyser See who is in a starter pack, with stats and bots. | GET /api/v1/tools/starter-pack-analyser | 5 minutes | Depends on the request |
| Post and thread viewer Read any public Bluesky post or thread, no account needed. | GET /api/v1/tools/post-viewer | 60 seconds | 3 unit(s) |
| Feed inspector Preview a custom feed and find out why it shows nothing. | GET /api/v1/tools/feed-inspector | Not cached | 3 unit(s) |
| Label inspector See who applied a label and what it means. | GET /api/v1/tools/label-inspector | 5 minutes | Depends on the request |
| Follower list export Back up a public follower or following list as CSV. | GET /api/v1/tools/follower-export | 5 minutes | 2 unit(s) |
| Repository explorer Browse an account’s public records on its own data server. | GET /api/v1/tools/repo-explorer | 5 minutes | 2 unit(s) |
Three examples we actually ran
The snippets below were run against our official account. Each output is a dated capture, not a canned response. Public data and response details can change. Python uses a descriptive User-Agent: the default Python-urllib agent was refused by the edge with HTTP 403 during this check.
curl --fail --silent --show-error 'https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot'const response = await fetch(
"https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot",
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(JSON.stringify(await response.json()));import json
from urllib.request import Request, urlopen
request = Request('https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot', headers={'User-Agent': 'Bluesky.bot-docs/1.0 (+https://bluesky.bot/tools/api)'})
with urlopen(request, timeout=10) as response:
print(json.dumps(json.load(response)))Input
curl --fail --silent --show-error 'https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot'
Captured output
{
"tool": "did-finder",
"url": "https://bluesky.bot/tools/did-finder",
"result": {
"status": "found",
"handle": "bluesky.bot",
"unicodeHandle": null,
"dns": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"https": {
"status": "none"
},
"appview": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5",
"method": "dns",
"verified": true,
"claimedHandle": null,
"warnings": []
}
}Input
const response = await fetch('https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(JSON.stringify(await response.json()));Captured output
{
"tool": "did-finder",
"url": "https://bluesky.bot/tools/did-finder",
"result": {
"status": "found",
"handle": "bluesky.bot",
"unicodeHandle": null,
"dns": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"https": {
"status": "none"
},
"appview": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5",
"method": "dns",
"verified": true,
"claimedHandle": null,
"warnings": []
}
}Input
import json
from urllib.request import Request, urlopen
request = Request('https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot', headers={'User-Agent': 'Bluesky.bot-docs/1.0 (+https://bluesky.bot/tools/api)'})
with urlopen(request, timeout=10) as response:
print(json.dumps(json.load(response)))Captured output
{
"tool": "did-finder",
"url": "https://bluesky.bot/tools/did-finder",
"result": {
"status": "found",
"handle": "bluesky.bot",
"unicodeHandle": null,
"dns": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"https": {
"status": "none"
},
"appview": {
"status": "found",
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5"
},
"did": "did:plc:ulmk4vmvoobkemd3w2tkwhu5",
"method": "dns",
"verified": true,
"claimedHandle": null,
"warnings": []
}
}Limits and fair use
Anonymous: 60 quota units per 60 seconds and 2000 per 24 hours. A valid creator token raises both limits by 10 times when its owner has at least one active bot.
A call consumes its tool’s weight in both quotas. Server lookups also share an upstream budget; complex checks can be refused before your own quota runs out.
HTTP 429 includes Retry-After. Invalid inputs return 400, a missing result 404 and an upstream failure 502, with the API v1 error shape. Public GET responses allow cross-origin reads; token failures are refused instead of silently falling back to anonymous access.
We count the tool and channel, not your input. Tool-input query strings are excluded from access logs. Do not send secrets, private posts or another person’s credentials.
The service is free and best effort, without an uptime SLA. Reuse cacheable results, respect retry delays and contact us for a different use case.
When to call something else
For bulk posts, live network events or a long-running consumer, use the AT Protocol services or Jetstream directly. A bounded lookup API is a poor bulk export or firehose client. For writing, use an account-authorized client; for AI clients, see our MCP server. The API reference and tools reference cover parameters and errors.
Prefer a terminal? Compare the Bluesky command-line clients, including the published bsbot version and its current limits.
Questions
Is the Bluesky API free?
Bluesky’s public AppView provides many unauthenticated reads without a key. Limits apply. Our public tools API is also free.
Can this API publish posts?
No. The tools API reads public information and performs computations. Account-authorized writes belong to a separate client.
Do I need a Bluesky.bot token?
No for public tools. Eligible creator tokens raise the quota and do not remove upstream limits.
Where are the parameters and error schemas?
Use the API and tools reference in the developer docs and the OpenAPI document.