API

Analytics

Read and export how documents are read, and how short links and QR codes are visited.

Viewer analytics count what readers do in published documents: views, reader sessions, page views, links followed, downloads, embed loads, lead forms sent, enrichment items used and time on page, with the country, device and referring site of views and how far readers read. Link analytics count visits to short links and QR codes, by link and by day. Bots are left out of both, and nothing is recorded for anyone who asks not to be tracked (DNT: 1 or Global Privacy Control).

Every report takes a range of UTC days, from and to as YYYY-MM-DD, both inclusive, covering at most 366 days. A range with nothing recorded gives recorded: null, not zeros. Figures are kept per document and UTC day, so a reader session that runs past midnight counts on both days. The CSV exports give the same daily figures row by row.

Viewer analytics need the plan's analytics feature and are recorded only while the workspace has analytics on. Link and QR analytics need QR tracking, and tracking says whether visits are being recorded now. What was recorded before tracking was turned off is still reported.

Views, readers, pages, link hits, downloads, embed loads and time on page across the workspace

GET /analytics analytics.workspace

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. A range with no events has recorded: null. readers is the sum, over each document and UTC day, of the distinct reader sessions that opened it: a session that runs past midnight counts on both days. Bots are left out.

The figures count every document in the workspace, those in the trash and those the caller cannot open included.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise
MCP tool
analytics_workspace

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. A JSON object:

Response fields (21)
NameTypeDescription
from string The first UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
recorded object The figures, or null when the range has no recorded events (not a row of zeros). Can be null.
recorded.views number Times a publication was opened in the viewer.
recorded.readers number Distinct reader sessions that opened a publication, summed over each document and UTC day. A session is one load of the viewer page, not a person.
recorded.pages array of objects Views of each page, by page number. A page counts once a reader stays on it for a moment. Pages never viewed are absent.
recorded.pages[].page number The page, 1-based.
recorded.pages[].views number Times it was viewed.
recorded.links array of objects Links inside the publication that readers followed, by address, the most followed first.
recorded.links[].url string The link's address.
recorded.links[].hits number Times it was followed.
recorded.downloads number Clicks on the viewer's download button.
recorded.embedLoads number Times the publication opened in an embed on another site.
recorded.leads number Lead forms sent (conversions), counted like the other figures. The submissions themselves are at GET /api/v1/documents/{documentId}/leads.
recorded.enrichment array of objects Uses of each enrichment item, the most first: a hotspot's note opened, a call to action followed, a video played, a gallery opened.
recorded.enrichment[].item string The enrichment item's id, as GET /api/v1/documents/{documentId}/enrichment lists it.
recorded.enrichment[].hits number Times it was used.
recorded.dwell array of objects Time on each page while the reader's tab was visible. A measurement under 1 second is not sent and one over 10 minutes counts as 10 minutes. Pages with no measurement are absent.
recorded.dwell[].page number The page, 1-based.
recorded.dwell[].samples number How many times a reader's time on it was measured.
recorded.dwell[].averageMs number The mean of those measurements, in milliseconds, rounded.

Example request

curl "https://api.flipbird.io/api/v1/analytics?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "recorded": {
    "views": 1,
    "readers": 1,
    "pages": [
      {
        "page": 1,
        "views": 1
      }
    ],
    "links": [
      {
        "url": "https://example.com/privacy",
        "hits": 1
      }
    ],
    "downloads": 1,
    "embedLoads": 1,
    "leads": 1,
    "enrichment": [
      {
        "item": "string",
        "hits": 1
      }
    ],
    "dwell": [
      {
        "page": 1,
        "samples": 1,
        "averageMs": 1
      }
    ]
  }
}

Views, readers, pages, link hits, downloads, embed loads and time on page for one document

GET /documents/{documentId}/analytics analytics.document

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. A range with no events has recorded: null. readers is the sum, over each UTC day, of the distinct reader sessions that opened the document: a session that runs past midnight counts on both days. Bots are left out.

A document that does not exist, is in the trash, or the caller cannot open answers 404 not_found.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise
MCP tool
analytics_document

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. A JSON object:

Response fields (21)
NameTypeDescription
from string The first UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
recorded object The figures, or null when the range has no recorded events (not a row of zeros). Can be null.
recorded.views number Times a publication was opened in the viewer.
recorded.readers number Distinct reader sessions that opened a publication, summed over each document and UTC day. A session is one load of the viewer page, not a person.
recorded.pages array of objects Views of each page, by page number. A page counts once a reader stays on it for a moment. Pages never viewed are absent.
recorded.pages[].page number The page, 1-based.
recorded.pages[].views number Times it was viewed.
recorded.links array of objects Links inside the publication that readers followed, by address, the most followed first.
recorded.links[].url string The link's address.
recorded.links[].hits number Times it was followed.
recorded.downloads number Clicks on the viewer's download button.
recorded.embedLoads number Times the publication opened in an embed on another site.
recorded.leads number Lead forms sent (conversions), counted like the other figures. The submissions themselves are at GET /api/v1/documents/{documentId}/leads.
recorded.enrichment array of objects Uses of each enrichment item, the most first: a hotspot's note opened, a call to action followed, a video played, a gallery opened.
recorded.enrichment[].item string The enrichment item's id, as GET /api/v1/documents/{documentId}/enrichment lists it.
recorded.enrichment[].hits number Times it was used.
recorded.dwell array of objects Time on each page while the reader's tab was visible. A measurement under 1 second is not sent and one over 10 minutes counts as 10 minutes. Pages with no measurement are absent.
recorded.dwell[].page number The page, 1-based.
recorded.dwell[].samples number How many times a reader's time on it was measured.
recorded.dwell[].averageMs number The mean of those measurements, in milliseconds, rounded.

Example request

curl "https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/analytics?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "recorded": {
    "views": 1,
    "readers": 1,
    "pages": [
      {
        "page": 1,
        "views": 1
      }
    ],
    "links": [
      {
        "url": "https://example.com/privacy",
        "hits": 1
      }
    ],
    "downloads": 1,
    "embedLoads": 1,
    "leads": 1,
    "enrichment": [
      {
        "item": "string",
        "hits": 1
      }
    ],
    "dwell": [
      {
        "page": 1,
        "samples": 1,
        "averageMs": 1
      }
    ]
  }
}

QR scans in a range, for the workspace or one document

GET /qr-analytics analytics.qr

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. Each QR code's scans in the range, bots left out; scans of an archived or expired code count too. A per-recipient variant is its own code. With documentId, only the codes assigned to that document; one that does not exist, is in the trash, or the caller cannot open answers 404 not_found.

recorded is null when no scans were recorded in the range.

Scopes
links.read
Plan
Scan tracking, on Pro, Enterprise
MCP tool
analytics_qr

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.
documentId string Only the QR codes assigned to this document, which the caller must be able to open. Omitted counts every QR code in the workspace. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (10)
NameTypeDescription
from string The first UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
tracking boolean Whether scans are being recorded now. False when the workspace has turned scan tracking off (its plan still includes it); scans recorded before are still reported.
recorded object The scans, or null when none were recorded in the range. Can be null.
recorded.scans number Scans in the range, bots left out.
recorded.codes array of objects Each code scanned in the range, the most scanned first.
recorded.codes[].linkId string The QR code's link id.
recorded.codes[].code string Its short code.
recorded.codes[].label string Its label; empty when it has none.
recorded.codes[].scans number Its scans in the range.

Example request

curl "https://api.flipbird.io/api/v1/qr-analytics?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "tracking": true,
  "recorded": {
    "scans": 1,
    "codes": [
      {
        "linkId": "…",
        "code": "string",
        "label": "Spring campaign",
        "scans": 1
      }
    ]
  }
}

Daily views across the workspace, with countries, devices, referring sites, read-through depth, top documents and top pages

GET /analytics/insights analytics.workspaceInsights

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. Country, device and referring site are counted on views; depth on reader sessions per document and UTC day, against the length of the edition they were shown. Those figures start with the release that records them; older days have none. Bots are left out.

A range with no events has recorded: null. documents and pages list at most 20 each, the most views first, and leave out documents in the trash and those the caller cannot open; the other figures count every document.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise
MCP tool
analytics_workspace_insights

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. A JSON object:

Response fields (33)
NameTypeDescription
from string The first UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
recorded object The figures, or null when the range has no recorded events. Can be null.
recorded.series array of objects Every UTC day of the range, oldest first; a day without events has zeros.
recorded.series[].day number The day's start: UTC midnight, epoch milliseconds.
recorded.series[].views number Times a publication was opened that day.
recorded.series[].readers number Distinct reader sessions that opened a publication that day, summed over documents.
recorded.series[].pageViews number Page views that day, over every page.
recorded.series[].linkHits number Links inside publications followed that day. Visits to short links are in GET /api/v1/link-analytics.
recorded.series[].downloads number Clicks on the viewer's download button that day.
recorded.countries array of objects Views by the reader's country, the most first: item is an ISO 3166-1 alpha-2 code (T1 for Tor), or empty when unknown.
recorded.countries[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.countries[].views number Views with that value.
recorded.devices array of objects Views by device class, the most first: item is mobile, tablet, desktop or unknown, or empty for views recorded before the device was.
recorded.devices[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.devices[].views number Views with that value.
recorded.referrers array of objects Views by the referring site's host name, the most first, at most 50: item is empty for views with no referring site.
recorded.referrers[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.referrers[].views number Views with that value.
recorded.depth object Read-through depth, counted per reader session, document and UTC day, against the length of the edition shown.
recorded.depth.opened number Reader sessions that opened an edition of known length.
recorded.depth.half number Reader sessions that turned to at least half of its pages.
recorded.depth.end number Reader sessions that turned to its last page.
recorded.documents array of objects The most viewed documents, at most 20, the most views first. Documents in the trash and those the caller cannot open are left out.
recorded.documents[].documentId string The document's id.
recorded.documents[].title string Its title.
recorded.documents[].views number Its views in the range.
recorded.documents[].readers number Its reader sessions in the range, summed over UTC days.
recorded.pages array of objects The most viewed pages across documents, at most 20, the most views first, left out as for documents.
recorded.pages[].documentId string The document's id.
recorded.pages[].title string Its title.
recorded.pages[].page number The page, 1-based.
recorded.pages[].views number Views of that page in the range.

Example request

curl "https://api.flipbird.io/api/v1/analytics/insights?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "recorded": {
    "series": [
      {
        "day": 1,
        "views": 1,
        "readers": 1,
        "pageViews": 1,
        "linkHits": 1,
        "downloads": 1
      }
    ],
    "countries": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "devices": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "referrers": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "depth": {
      "opened": 1,
      "half": 1,
      "end": 1
    },
    "documents": [
      {
        "documentId": "…",
        "title": "Spring catalogue",
        "views": 1,
        "readers": 1
      }
    ],
    "pages": [
      {
        "documentId": "…",
        "title": "Spring catalogue",
        "page": 1,
        "views": 1
      }
    ]
  }
}

Daily views of one document, with countries, devices, referring sites and read-through depth

GET /documents/{documentId}/analytics/insights analytics.documentInsights

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. Country, device and referring site are counted on views; depth on reader sessions per document and UTC day, against the length of the edition they were shown. Those figures start with the release that records them; older days have none. Bots are left out.

A range with no events has recorded: null. A document the caller cannot open answers 404 not_found.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise
MCP tool
analytics_document_insights

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. A JSON object:

Response fields (23)
NameTypeDescription
from string The first UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last UTC day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
recorded object The figures, or null when the range has no recorded events. Can be null.
recorded.series array of objects Every UTC day of the range, oldest first; a day without events has zeros.
recorded.series[].day number The day's start: UTC midnight, epoch milliseconds.
recorded.series[].views number Times a publication was opened that day.
recorded.series[].readers number Distinct reader sessions that opened a publication that day, summed over documents.
recorded.series[].pageViews number Page views that day, over every page.
recorded.series[].linkHits number Links inside publications followed that day. Visits to short links are in GET /api/v1/link-analytics.
recorded.series[].downloads number Clicks on the viewer's download button that day.
recorded.countries array of objects Views by the reader's country, the most first: item is an ISO 3166-1 alpha-2 code (T1 for Tor), or empty when unknown.
recorded.countries[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.countries[].views number Views with that value.
recorded.devices array of objects Views by device class, the most first: item is mobile, tablet, desktop or unknown, or empty for views recorded before the device was.
recorded.devices[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.devices[].views number Views with that value.
recorded.referrers array of objects Views by the referring site's host name, the most first, at most 50: item is empty for views with no referring site.
recorded.referrers[].item string The value counted: a country code, a device class or a host name, as the list says.
recorded.referrers[].views number Views with that value.
recorded.depth object Read-through depth, counted per reader session, document and UTC day, against the length of the edition shown.
recorded.depth.opened number Reader sessions that opened an edition of known length.
recorded.depth.half number Reader sessions that turned to at least half of its pages.
recorded.depth.end number Reader sessions that turned to its last page.

Example request

curl "https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/analytics/insights?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "recorded": {
    "series": [
      {
        "day": 1,
        "views": 1,
        "readers": 1,
        "pageViews": 1,
        "linkHits": 1,
        "downloads": 1
      }
    ],
    "countries": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "devices": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "referrers": [
      {
        "item": "string",
        "views": 1
      }
    ],
    "depth": {
      "opened": 1,
      "half": 1,
      "end": 1
    }
  }
}

The workspace's daily analytics as CSV

GET /analytics/export analytics.workspaceExport

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. A CSV file (text/csv, UTF-8, CRLF line ends) with one row per document, UTC day, metric and item, as the daily rollups keep them, sorted by day, document, metric and item. Columns: day (YYYY-MM-DD), document_id, document (its title), metric, item, value.

metric is views, readers, page (item: the page), link (item: the URL), downloads, embed_loads, leads, enrichment (item: the enrichment item's id), dwell_ms and dwell_n (item: the page; the total milliseconds measured and the number of measurements), country, device, referrer (item: the value) or depth (item: opened, half or end). Bots are left out.

Days not yet rolled up are computed the same way. Cells a spreadsheet would run as a formula are prefixed with an apostrophe. The file is named analytics-{from}-to-{to}.csv. Documents the caller cannot open, and those deleted for good, are left out.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl "https://api.flipbird.io/api/v1/analytics/export?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

One document's daily analytics as CSV

GET /documents/{documentId}/analytics/export analytics.documentExport

from and to are UTC days, inclusive. A range that runs backwards or covers more than 366 days answers 400 bad_range. A CSV file (text/csv, UTF-8, CRLF line ends) with one row per document, UTC day, metric and item, as the daily rollups keep them, sorted by day, document, metric and item. Columns: day (YYYY-MM-DD), document_id, document (its title), metric, item, value.

metric is views, readers, page (item: the page), link (item: the URL), downloads, embed_loads, leads, enrichment (item: the enrichment item's id), dwell_ms and dwell_n (item: the page; the total milliseconds measured and the number of measurements), country, device, referrer (item: the value) or depth (item: opened, half or end). Bots are left out.

Days not yet rolled up are computed the same way. Cells a spreadsheet would run as a formula are prefixed with an apostrophe. The file is named analytics-{documentId}-{from}-to-{to}.csv. A document the caller cannot open answers 404 not_found.

Scopes
documents.read
Plan
Publication analytics, on Pro, Enterprise

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Query parameters

NameTypeDescription
from required string The first UTC day of the range, as YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last UTC day of the range, inclusive, as YYYY-MM-DD. The range covers at most 366 days. Matches ^\d{4}-\d{2}-\d{2}$.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl "https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/analytics/export?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
400bad_rangeThe range runs backwards, covers more than 366 days, or is not a valid YYYY-MM-DD.