Polling for new transmissions
To keep up with a feed, read its newest page once, then ask every minute or so for just the transmissions that are new since then. Each check is usually one read, and a transmission sent between checks isn't skipped.
Feeds you can poll
- A user's transmissions:
/v2/users/{username}/transmissions - A Site's transmissions:
/v2/sites/{siteName}/transmissions - One hashtag:
/v2/hashtags/{tag}/transmissions - Several hashtags:
/v2/hashtags/transmissions?tag=…&tag=…
Hub feeds and classified ads can't be polled: they ignore newerThan and return their newest page, so re-read that instead.
The loop
- Read the newest page, without
cursorornewerThan. Keep its transmissions, and keeppaging.newestCursor. - Poll: call the same feed with
newerThanset to thenewestCursoryou kept. Keep the transmissions that come back, and replace yournewestCursorwith the response's. - If
hasMoreistrue, poll again at once with the newnewestCursor, until it'sfalse. A poll returns at mosttaketransmissions: the oldesttakeof the new ones, listed newest first. So a backlog arrives in several calls, the oldest batch first. - Wait about a minute (see the budget), then go back to step 2.
curl "https://api.blazot.com/v2/users/exampleuser/transmissions?newerThan=NjM5MTMyNTE5MDAwMDAwMDAwOjJhOWIzZDFlNmY1YTdjMmQ5MDhmMTRlNDVmY2VlYTRj" \
--header "Authorization: Bearer $BLAZOT_TOKEN"{
"data": [
{ "transmissionId": "5c7d1e2f-3a4b-4c8d-9e0f-1a2b3c4d5e6f", "...": "..." }
],
"paging": {
"nextCursor": null,
"hasMore": false,
"newestCursor": "NjM5MTMyNTIyNjAwMDAwMDAwOjVjN2QxZTJmM2E0YjRjOGQ5ZTBmMWEyYjNjNGQ1ZTZm"
}
}A few things to know:
- Every newest page and every poll has a
newestCursor, even the newest page of an empty feed and a poll that found nothing, so you can always keep polling. (A page fetched withcursorhas none.) - Keep
newestCursorsomewhere that survives a restart, and poll from it when you start again. It doesn't expire; if a stored cursor ever comes back as a400, start again from the newest page. The newest page shows only the latesttaketransmissions, so starting over from it can miss what arrived while you were down. - Pages are newest first, polls included.
nextCursoris alwaysnullon a poll. - Send the same parameters every time.
includeRelays,includeHubTransmissions, the tags andtakearen't part of the cursor. To change them, start again from the newest page. cursorandnewerThandon't mix: sending both is a400.- On a
429, waitRetry-Afterseconds, plus one, and poll again from the samenewestCursor. The cursor keeps your place, so nothing is lost, and a refused call doesn't count against your budget.
Why a transmission can arrive twice
Polls return only transmissions at least a minute old, so that a new transmission's images and hashtags are in place before you get it. The newest page shows newer ones too, but its newestCursor stops before them, so the next poll or two returns them again, complete.
So store transmissions by transmissionId, and let a later copy replace the earlier one. In practice, polling once a minute, a new transmission reaches you one to two minutes after it was transmitted.
What polling doesn't tell you
A poll returns transmissions newer than your cursor, and nothing else. It doesn't report:
- Edits. An edited transmission keeps its place in the feed, so a poll never returns it again; only its
bodyanddateEditedchange. - Deletions, or a transmission you can no longer see, for example because its author blocked you or became unavailable.
- Transmissions that become visible late, more than a minute after their
dateTransmitted: for example when an author's account is restored, an author unblocks you, or you stop ignoring someone. Their place in the feed is already behind your cursor.
To keep up with those, re-read the newest page now and then and compare it with what you hold, and fetch a single transmission with /v2/transmissions/{transmissionId}: a 404 means it's gone or you can no longer see it. Each of these is a read, so leave room for them in your budget.
A worked loop
Both samples get a token once and reuse it, poll one feed every 60 seconds, follow hasMore, renew the token when a read says it has stopped working, and wait out a 429. They print each transmission the first time they see it. Like the Quickstart, they read the key and secret from BLAZOT_API_KEY and BLAZOT_API_SECRET, and run on your server.
C#
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
var apiKey = Environment.GetEnvironmentVariable("BLAZOT_API_KEY")!;
var apiSecret = Environment.GetEnvironmentVariable("BLAZOT_API_SECRET")!;
const string feed = "/v2/users/exampleuser/transmissions?includeRelays=false&take=25";
using var http = new HttpClient { BaseAddress = new Uri("https://api.blazot.com") };
string? token = null;
var transmissions = new Dictionary<Guid, Transmission>();
// The newest page, and the cursor to poll from.
var page = await ReadAsync(feed);
Store(page);
var newestCursor = page.Paging.NewestCursor!;
while (true)
{
await Task.Delay(TimeSpan.FromSeconds(60));
// Poll with the same parameters; while more are waiting, poll again at once.
do
{
page = await ReadAsync($"{feed}&newerThan={Uri.EscapeDataString(newestCursor)}");
Store(page);
newestCursor = page.Paging.NewestCursor!;
}
while (page.Paging.HasMore);
}
// Store by id: a later copy replaces the earlier one.
void Store(Page result)
{
foreach (var t in result.Data.Reverse()) // oldest first, so they print in order
{
if (!transmissions.ContainsKey(t.TransmissionId))
Console.WriteLine($"{t.DateTransmitted:u} @{t.Author.UserName}: {t.Body}");
transmissions[t.TransmissionId] = t;
}
}
async Task<Page> ReadAsync(string path)
{
var renewed = false;
while (true)
{
token ??= await GetTokenAsync();
using var request = new HttpRequestMessage(HttpMethod.Get, path);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using var response = await http.SendAsync(request);
// The token expired or stopped working: get a new one, once.
if (response.StatusCode == HttpStatusCode.Unauthorized && response.Headers.WwwAuthenticate.Count > 0 && !renewed)
{
token = null;
renewed = true;
continue;
}
// Over the read budget: wait as long as the API says, plus a second, then try again.
if (response.StatusCode == HttpStatusCode.TooManyRequests)
{
var retryAfter = response.Headers.RetryAfter?.Delta;
await Task.Delay(retryAfter is null ? TimeSpan.FromSeconds(60) : retryAfter.Value + TimeSpan.FromSeconds(1));
continue;
}
response.EnsureSuccessStatusCode();
return (await response.Content.ReadFromJsonAsync<Page>())!;
}
}
async Task<string> GetTokenAsync()
{
using var request = new HttpRequestMessage(HttpMethod.Get, "/v2/auth/token");
request.Headers.Add("x-api-key", apiKey);
request.Headers.Add("x-secret-auth-key", apiSecret);
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
return (await response.Content.ReadFromJsonAsync<Token>())!.AccessToken;
}
record Token(string TokenType, string AccessToken, int ExpiresIn);
record Page(IReadOnlyList<Transmission> Data, Paging Paging);
record Paging(string? NextCursor, bool HasMore, string? NewestCursor);
record Transmission(Guid TransmissionId, DateTimeOffset DateTransmitted, string Body, Author Author);
record Author(string UserName);
JavaScript
For Node.js 18 or later. Save it as poll.mjs so await works at the top level.
const apiKey = process.env.BLAZOT_API_KEY;
const apiSecret = process.env.BLAZOT_API_SECRET;
const base = 'https://api.blazot.com';
const feed = '/v2/users/exampleuser/transmissions?includeRelays=false&take=25';
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
const transmissions = new Map();
let token = null;
async function getToken() {
const response = await fetch(`${base}/v2/auth/token`, {
headers: { 'x-api-key': apiKey, 'x-secret-auth-key': apiSecret },
});
if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
return (await response.json()).accessToken;
}
async function read(path) {
let renewed = false;
while (true) {
token ??= await getToken();
const response = await fetch(`${base}${path}`, {
headers: { Authorization: `Bearer ${token}` },
});
// The token expired or stopped working: get a new one, once.
if (response.status === 401 && response.headers.has('www-authenticate') && !renewed) {
token = null;
renewed = true;
continue;
}
// Over the read budget: wait as long as the API says, plus a second, then try again.
if (response.status === 429) {
const retryAfter = Number.parseInt(response.headers.get('retry-after'), 10);
await sleep(Number.isNaN(retryAfter) ? 60 : retryAfter + 1);
continue;
}
if (!response.ok) throw new Error(`Read failed: ${response.status}`);
return response.json();
}
}
// Store by id: a later copy replaces the earlier one.
function store(page) {
for (const t of [...page.data].reverse()) { // oldest first, so they print in order
if (!transmissions.has(t.transmissionId)) {
console.log(`${t.dateTransmitted} @${t.author.userName}: ${t.body}`);
}
transmissions.set(t.transmissionId, t);
}
}
// The newest page, and the cursor to poll from.
let page = await read(feed);
store(page);
let newestCursor = page.paging.newestCursor;
while (true) {
await sleep(60);
// Poll with the same parameters; while more are waiting, poll again at once.
do {
page = await read(`${feed}&newerThan=${encodeURIComponent(newestCursor)}`);
store(page);
newestCursor = page.paging.newestCursor;
} while (page.paging.hasMore);
}
A long-running app should renew the token a minute or so before expiresIn runs out, as Authentication describes, though renewing on the first 401, as here, works too. It should survive a failed read as well, such as a 500 or a network error: wait a little and poll again from the same newestCursor rather than stopping. The samples leave that out to stay short.
The budget
Every poll is a read, and reads come out of your account's budget, shared by all your calls: 25 per 15 minutes without a subscription or at level 0. A window runs 15 minutes from your first read in it, and a call made exactly 15 minutes after that first read still lands in it: at one call a minute, that's up to 16 calls. That leaves 9 of level 0's reads for the hasMore follow-ups, and the re-reads that catch edits and deletions.
That's why a minute is a good interval at level 0. It's a choice, not a rule:
- Polling faster gets transmissions to you a little sooner, but never sooner than a minute after they were transmitted, and spends more reads.
- Each feed you poll costs its own reads, except that several hashtags can share one feed:
/v2/hashtags/transmissions?tag=…&tag=…is one read for up to 10 tags. To poll several feeds at level 0, poll each less often, or move to a higher level: Rate limits has the budget for each.