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 endpoints
ToolEndpointHTTP cacheQuota cost
Declared automation checker

See the automation signals an account makes public.

GET /api/v1/tools/bot-checker60 seconds3 unit(s)
DID finder

Get the DID behind any Bluesky handle.

GET /api/v1/tools/did-finder60 seconds1 unit(s)
Handle finder (DID to handle)

Find the handle behind a DID.

GET /api/v1/tools/handle-finder60 seconds1 unit(s)
Bluesky whois

Everything public about a handle or a DID.

GET /api/v1/tools/whois60 seconds3 unit(s)
Account age checker

See when any account joined Bluesky.

GET /api/v1/tools/account-age60 seconds1 unit(s)
AT-URI converter

Turn a bsky.app link into an at:// URI, and back.

GET /api/v1/tools/at-uri-converter60 seconds1 unit(s)
TID decoder

Read the date hidden in a record key.

GET /api/v1/tools/tid-decoder1 year1 unit(s)
Post character counter

Count your post the way Bluesky does.

GET /api/v1/tools/character-counter1 year1 unit(s)
Rich text facet builder

Mentions, links and hashtags with their byte offsets.

GET /api/v1/tools/facet-builderNot cachedDepends 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-checkerNot cached2 unit(s)
Handle availability checker

Is your name free on Bluesky?

GET /api/v1/tools/handle-availabilityNot cached1 unit(s)
PLC history viewer

Every handle change, server move and key change of an account.

GET /api/v1/tools/plc-history5 minutes2 unit(s)
Starter pack analyser

See who is in a starter pack, with stats and bots.

GET /api/v1/tools/starter-pack-analyser5 minutesDepends on the request
Post and thread viewer

Read any public Bluesky post or thread, no account needed.

GET /api/v1/tools/post-viewer60 seconds3 unit(s)
Feed inspector

Preview a custom feed and find out why it shows nothing.

GET /api/v1/tools/feed-inspectorNot cached3 unit(s)
Label inspector

See who applied a label and what it means.

GET /api/v1/tools/label-inspector5 minutesDepends on the request
Follower list export

Back up a public follower or following list as CSV.

GET /api/v1/tools/follower-export5 minutes2 unit(s)
Repository explorer

Browse an account’s public records on its own data server.

GET /api/v1/tools/repo-explorer5 minutes2 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
curl --fail --silent --show-error 'https://bluesky.bot/api/v1/tools/did-finder?handle=bluesky.bot'
JavaScript (Node.js 24)
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()));
Python 3
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

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": []
  }
}
Captured

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": []
  }
}
Captured

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.

Sources