Analytics changed since a cursor
curl --request GET \
--url https://api.aisa.one/apis/v1/social/analytics/delta \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aisa.one/apis/v1/social/analytics/delta"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aisa.one/apis/v1/social/analytics/delta', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/social/analytics/delta",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/social/analytics/delta"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aisa.one/apis/v1/social/analytics/delta")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/social/analytics/delta")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"accountId": "<string>",
"isDeleted": true,
"metrics": {
"audienceCountries": {},
"audienceTypes": {},
"clicks": 123,
"comments": 123,
"completionRate": 123,
"follows": 123,
"igReelsAvgWatchTime": 123,
"igReelsVideoViewTotalTime": 123,
"impressionSources": {},
"impressions": 123,
"likes": 123,
"profileViews": 123,
"reach": 123,
"reelsSkipRate": 123,
"reposts": 123,
"saves": 123,
"sends": 123,
"shares": 123,
"views": 123,
"websiteClicks": 123,
"replays": 123,
"retentionCurve": {}
},
"platform": "<string>",
"platformPostId": "<string>",
"postId": "<string>",
"profileId": "<string>",
"publishedAt": "2023-11-07T05:31:56Z",
"syncedAt": "2023-11-07T05:31:56Z"
}
],
"hasMore": true,
"nextCursor": "<string>"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "never",
"retryable": true,
"type": "<string>"
}
}AIsa Social
Analytics changed since a cursor
Analytics. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Without profileId or accountId it reads your default profile.
Cursor feed of the analytics snapshots that CHANGED, across every account you can read, in one paginated stream. Built for integrations that would otherwise call `GET /apis/v1/social/analytics` once per connected account.
Each page carries changes from many accounts at once, so your call count scales with how much actually changed rather than with how many accounts you have.
Measured against a fleet of roughly 1,600 connected accounts: about 1,599 per-account analytics calls an hour became about 205 delta calls an hour, a 7.8x reduction.
### Bootstrap once, then stay in sync
1. Take the cursor FIRST: call this endpoint with NO `cursor`. It answers with an empty `data` array plus the feed's current position in `nextCursor`.
2. Load your baseline from `GET /apis/v1/social/analytics`, the historical endpoint. This one is a rolling 7-day change log and cannot replay history.
3. Resume from the cursor you took before the baseline.
Taking the cursor afterwards instead drops every change that lands while the baseline is loading: it is in neither the row you already read nor the feed you resume behind it.
The overlap this order creates is safe. Metrics are absolute values rather than increments, so draining it leaves every post on its newest value.
`nextCursor` is present on every response, empty pages included, so you always have something to advance with.
### Ordering
Entries come back oldest first, in the order the feed received them. That order is NOT `syncedAt`. `syncedAt` is stamped when an account's sync cycle started, and a slow cycle writes its rows after a faster cycle that started later, so `syncedAt` can go backwards between consecutive entries.
Do not sort, filter or resume on `syncedAt`. The cursor is the only stable position, and it is opaque: pass it back verbatim, and do not parse, construct or compare cursors.
### `hasMore: false` does not mean the feed ended
This stream has no end and `nextCursor` is never null.
- `hasMore: true`: more changes are already waiting, so call again straight away.
- `hasMore: false`: you are caught up. Keep the cursor and poll again on your normal interval.
### The newest changes settle before they are served
The feed deliberately holds back its last few seconds of writes, so that a row can never become visible behind a cursor you have already advanced past.
A read issued the instant an `analytics.synced` webhook lands will therefore often return an empty page for that account. Do not read an empty page as "nothing changed": poll again with the SAME cursor you last used rather than advancing.
### Repeats inside one instant
A sync cycle occasionally records the same post twice at the same feed position. When that happens the feed delivers one of those rows, not both.
Measured over a day of production traffic, about 1.3% of rows fall in such a group and 99.4% of those groups are identical rows, so this is far more often deduplication than loss.
Metrics are absolute values rather than increments, so a later entry for the same post supersedes an earlier one.
### Retention is 7 days
Changes older than that leave the feed. A cursor older than 6 days is rejected with a `400` (a day of margin, because expiry is lazy).
Recover the same way you bootstrapped:
1. Take a fresh cursor from a call to this endpoint with no `cursor`.
2. Re-load from `GET /apis/v1/social/analytics`.
3. Resume from that cursor.
A consumer that polls at least daily never reaches this.
### Webhook and access
Pairs with the `analytics.synced` webhook, so changes can be read on notification instead of on a timer. That event carries no cursor of its own: keep using the `nextCursor` this endpoint gave you.
Requires the same analytics access as `GET /apis/v1/social/analytics`, and shares the stricter per-second rate-limit window applied to analytics endpoints.
<!-- aisa-pricing:start -->
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.
<!-- aisa-pricing:end -->
GET
https://api.aisa.one
/
apis
/
v1
/
social
/
analytics
/
delta
Analytics changed since a cursor
curl --request GET \
--url https://api.aisa.one/apis/v1/social/analytics/delta \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aisa.one/apis/v1/social/analytics/delta"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aisa.one/apis/v1/social/analytics/delta', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/social/analytics/delta",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/social/analytics/delta"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aisa.one/apis/v1/social/analytics/delta")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/social/analytics/delta")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"accountId": "<string>",
"isDeleted": true,
"metrics": {
"audienceCountries": {},
"audienceTypes": {},
"clicks": 123,
"comments": 123,
"completionRate": 123,
"follows": 123,
"igReelsAvgWatchTime": 123,
"igReelsVideoViewTotalTime": 123,
"impressionSources": {},
"impressions": 123,
"likes": 123,
"profileViews": 123,
"reach": 123,
"reelsSkipRate": 123,
"reposts": 123,
"saves": 123,
"sends": 123,
"shares": 123,
"views": 123,
"websiteClicks": 123,
"replays": 123,
"retentionCurve": {}
},
"platform": "<string>",
"platformPostId": "<string>",
"postId": "<string>",
"profileId": "<string>",
"publishedAt": "2023-11-07T05:31:56Z",
"syncedAt": "2023-11-07T05:31:56Z"
}
],
"hasMore": true,
"nextCursor": "<string>"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "never",
"retryable": true,
"type": "<string>"
}
}Request contract
- Method and path: GET /apis/v1/social/analytics/delta
- Availability: enabled
- Request URL template:
https://api.aisa.one/apis/v1/social/analytics/delta - cursor: query; optional
- limit: query; optional
- platform: query; optional
- profileId: query; optional
- Runtime facts: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd
{
"operationId": "get_aisa_social_apis_v1_social_analytics_delta",
"method": "GET",
"path": "/apis/v1/social/analytics/delta",
"servers": [
{
"url": "https://api.aisa.one"
}
],
"parameters": [
{
"description": "Opaque cursor from a previous response's `nextCursor`. Omit it to start from\nnow: the response is then an empty page carrying the feed's current position.\nRejected with a `400` when malformed, or when older than the retention window.",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page size. Out-of-range values are a 400, never a silent clamp.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Filter to a single platform (for example \"youtube\"). Omit for every platform.",
"in": "query",
"name": "platform",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.",
"in": "query",
"name": "profileId",
"required": false,
"schema": {
"pattern": "^prf_[0-9A-Za-z]{22}$",
"type": "string"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"x-aisa-status": "enabled",
"x-aisa-pricing": {
"description": "Included with your connected social accounts: AIsa does not charge per call.",
"kind": "no_customer_charge"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
}
}
Cost and request rules
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Opaque cursor from a previous response's nextCursor. Omit it to start from
now: the response is then an empty page carrying the feed's current position.
Rejected with a 400 when malformed, or when older than the retention window.
Page size. Out-of-range values are a 400, never a silent clamp.
Required range:
1 <= x <= 100Filter to a single platform (for example "youtube"). Omit for every platform.
One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.
Pattern:
^prf_[0-9A-Za-z]{22}$Response
One page of changed analytics
Changed snapshots, oldest first, in the order the feed received them. Empty on
the bootstrap call (no cursor supplied) and whenever nothing has changed
since your cursor.
Show child attributes
Show child attributes
True when more changes are already waiting past nextCursor, so call again
immediately. False means you are caught up: keep nextCursor and poll again
later. This feed never ends, so hasMore: false does NOT mean nextCursor
is null.
Cursor to send on the next call. ALWAYS present, including on an empty page, so you always have something to advance with, and it never moves backwards. Opaque: pass it back verbatim, and do not parse, construct or compare cursors.