Social Media Metrics API

API key and access

Your API key is issued by the Buzz agency. It starts with buzz_ck_ and is sent in the Authorization: Bearer buzz_ck_… header. Keys in the query string are not accepted — URLs end up in logs and browser history.

curl https://api.buzzmybrand.co/v1/accounts \
  -H "Authorization: Bearer buzz_ck_your_key"

The key grants read-only access to the metrics of your own accounts and nothing else. Keep it on your server: never call the API directly from a browser or a public website — anyone could read the key from the page.

Unknown, revoked and expired keys all return the same 401 invalid_key. If you think a key has leaked, contact your account manager — we will revoke it and issue a new one.

For security, every request is logged: time, method, path, response code, IP address and user agent. The log is kept for 90 days and is used only to investigate suspicious activity.

Format and periods

Responses are JSON in UTF-8. Most endpoints also return CSV — add ?format=csv. CSV works well with Looker Studio and with Google Sheets via Apps Script (UrlFetchApp.fetch with the key in the request headers; the built-in IMPORTDATA formula cannot send headers).

Periods are set with from and to in YYYY-MM-DD format, both inclusive. Without them you get the last 30 days. The maximum period is 400 days. Dates follow Moscow time (UTC+3); timestamps such as publishedAt are in UTC.

Rate limits: 60 requests per minute per key and 300 per minute per IP address. Above them you get 429 rate_limited — retry after a minute. Data is refreshed twice a day (08:00 and 20:00 Moscow time), so polling more often gives nothing new.

Metrics

Metric keys: followers, views, reach, likes, comments, shares, saves, watch_time_min, avg_view_sec, avg_view_pct, subscribers_gained, subscribers_lost, profile_views, website_clicks, total_interactions, skip_rate and others. The set depends on the platform: a metric the platform does not provide is simply absent from the response — absent is not zero.

• YouTube — analytics arrives with a delay of about two days. For channels above 1,000 subscribers the platform rounds the subscriber count to three significant digits; the exact growth is subscribers_gained − subscribers_lost. dislikes may be negative on some days — YouTube counts removed dislikes as a negative value.
• Instagram — follows and unfollows are only available as weekly windows, so they are not part of the daily series. Use the period summary to get their total.
• TikTok — the platform only exposes cumulative counters. Daily series are computed by us as the difference between snapshots and start from the day the account was connected.

History starts from the day an account was connected to the agency platform — earlier data is not available.

Errors

An error is a JSON object: {"error": "message", "code": "bad_range"}.

• 400 bad_range, bad_metrics — invalid parameters.
• 401 unauthorized, invalid_key — the key is missing or not valid.
• 404 not_found — the account is not among yours.
• 429 rate_limited — too many requests.
• 500 internal — a failure on our side. Retry later; if it persists, contact your account manager.

Endpoints

Base URL — https://api.buzzmybrand.co/v1. All endpoints are read-only.