Developers

On this page
Using the API

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

  1. Read the newest page, without cursor or newerThan. Keep its transmissions, and keep paging.newestCursor.
  2. Poll: call the same feed with newerThan set to the newestCursor you kept. Keep the transmissions that come back, and replace your newestCursor with the response's.
  3. If hasMore is true, poll again at once with the new newestCursor, until it's false. A poll returns at most take transmissions: the oldest take of the new ones, listed newest first. So a backlog arrives in several calls, the oldest batch first.
  4. Wait about a minute (see the budget), then go back to step 2.
Shell
curl "https://api.blazot.com/v2/users/exampleuser/transmissions?newerThan=NjM5MTMyNTE5MDAwMDAwMDAwOjJhOWIzZDFlNmY1YTdjMmQ5MDhmMTRlNDVmY2VlYTRj" \
  --header "Authorization: Bearer $BLAZOT_TOKEN"
JSON
{
  "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 with cursor has none.)
  • Keep newestCursor somewhere that survives a restart, and poll from it when you start again. It doesn't expire; if a stored cursor ever comes back as a 400, start again from the newest page. The newest page shows only the latest take transmissions, so starting over from it can miss what arrived while you were down.
  • Pages are newest first, polls included. nextCursor is always null on a poll.
  • Send the same parameters every time. includeRelays, includeHubTransmissions, the tags and take aren't part of the cursor. To change them, start again from the newest page.
  • cursor and newerThan don't mix: sending both is a 400.
  • On a 429, wait Retry-After seconds, plus one, and poll again from the same newestCursor. 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 body and dateEdited change.
  • 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#

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.

JavaScript

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.