Guides
The Social service has a GET /counts endpoint that returns totals for likes, shares and subscribes, for any Publication or Document. Use it to show live numbers alongside your content.
Note
This endpoint is separate from the @skyscribe-sdk/social React components. The components handle signing readers in and recording their action; GET /counts only reads totals, and needs no authentication.
GET https://social.skyscribe.app/counts
No API key or token is needed. It answers browser requests from any website (see CORS) and requests from your server.
| Param | Required | Description |
|---|---|---|
action_type | yes | recommend, subscribe, or share |
publication_uri | no | Only count actions on this Publication: the AT URI of its site.standard.publication record |
document_uri | no | Only count actions on this Document: the AT URI of its site.standard.document record |
origin | no | Only count actions made from this website, e.g. https://norobots.blog |
from | no | Start of the window: ISO 8601, a Unix timestamp in seconds, or relative (-7d) |
to | no | End of the window, in the same formats. Defaults to now |
group_by | no | document_uri, did, or day |
order_by | no | count (default) or date; only applies with group_by |
limit | no | 1–100, default 10; only applies with group_by |
Careful
Likes use the action_type recommend, not like, matching the underlying site.standard.graph.recommend collection. Passing like returns a 400 error.
Fetch the total number of likes for a Document:
const res = await fetch(
`https://social.skyscribe.app/counts?action_type=recommend&document_uri=${encodeURIComponent(documentUri)}`
);
const { count } = await res.json();
// count: 42
Fetch the current subscriber count for a site:
const res = await fetch(
`https://social.skyscribe.app/counts?action_type=subscribe&publication_uri=${encodeURIComponent(publicationUri)}`
);
const { count } = await res.json();
// count: 17
Pass from to count only a recent period. Relative values work for any number of days:
| Value | Meaning |
|---|---|
-7d | Past 7 days |
-14d | Past 14 days |
-30d | Past 30 days |
| ISO 8601 | e.g. 2026-06-01T00:00:00Z |
| Unix seconds | e.g. 1780272000 |
Combine from and to for a specific window, for example to compare this week with last week:
// This week
const thisWeek = await fetch(
`https://social.skyscribe.app/counts?action_type=subscribe&publication_uri=${encodeURIComponent(publicationUri)}&from=-7d`
).then((r) => r.json());
// The week before
const lastWeek = await fetch(
`https://social.skyscribe.app/counts?action_type=subscribe&publication_uri=${encodeURIComponent(publicationUri)}&from=-14d&to=-7d`
).then((r) => r.json());
const delta = thisWeek.count - lastWeek.count;
Note
A window can be at most 90 days long. Longer ranges return a 400 error.
Add group_by to break the count down by Document, reader or day. The response then has a groups array as well as the total:
{
"groups": [
{ "key": "at://did:plc:.../site.standard.document/3mp...", "count": 17 },
{ "key": "at://did:plc:.../site.standard.document/3mq...", "count": 9 }
],
"total": 42
}
Most shared Documents in the past 30 days:
const res = await fetch(
`https://social.skyscribe.app/counts?action_type=share&from=-30d&group_by=document_uri&order_by=count&limit=10`
);
const { groups, total } = await res.json();
Daily like counts over the past week (for a sparkline):
const res = await fetch(
`https://social.skyscribe.app/counts?action_type=recommend&publication_uri=${encodeURIComponent(publicationUri)}&from=-7d&group_by=day&order_by=date`
);
const { groups } = await res.json();
// groups: [{ key: "2026-06-26", count: 3 }, { key: "2026-06-27", count: 1 }, ...]
For SSR frameworks, fetch counts in your route loader alongside the Document to avoid client-side waterfalls:
// app/routes/blog.$slug.tsx (React Router v7/v8)
export async function loader({ request, params }: LoaderFunctionArgs) {
const document = await fetchDocumentBySlug(
'alice.bsky.social',
'https://alice.bsky.social',
params.slug,
request.signal,
);
const likeCount = await fetch(
`https://social.skyscribe.app/counts?action_type=recommend&document_uri=${encodeURIComponent(document.uri)}`
).then((r) => r.json()).then((d) => d.count as number).catch(() => null);
return { document, likeCount };
}
The .catch(() => null) means a Social service outage can't break your Document page.
/counts answers browser requests from any website (Access-Control-Allow-Origin: *): the counts are public totals. Fetching them on the server is still worth it, for the rate limit below.
The endpoint allows 60 requests per minute per IP address. Beyond that you get 429 Too Many Requests. If you fetch counts on the server for every page view, a busy site can hit this, so cache the counts for a minute or two.
The AT URIs for publication_uri and document_uri come from your Publication and Document:
import { fetchPublication, fetchDocumentBySlug } from '@skyscribe-sdk/core';
const publication = await fetchPublication('alice.bsky.social', 'https://alice.bsky.social');
// publication.uri → publication_uri
const document = await fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', slug);
// document.uri → document_uri
See Concepts for more on AT URIs.