# Zilfu — Analytics 3 operations. Schemas referenced below are documented at https://zilfu.app/docs/api/schemas.md. ## Servers - `https://zilfu.app/api` ## Operations ### List analytics summaries - **Method:** `GET` - **Path:** `/spaces/{space}/analytics` - **Tags:** Analytics One compact row per account in the space — never merged — so a caller can see each account's collection health before drilling into one of them. Defaults to the last 7 days in the space timezone. #### Parameters ##### `space` required - **In:** `path` The space ID `integer` ##### `from` - **In:** `query` `string`, format: `date-time` ##### `to` - **In:** `query` `string`, format: `date-time` #### Responses ##### Status: 200 Array of \`AccountReportSummaryResource\` ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`account` (required)** `object` — The account this row describes. - **`avatar` (required)** `string | null` - **`disconnected_at` (required)** `string | null` - **`display_name` (required)** `string` - **`handler` (required)** `string | null` - **`id` (required)** `integer` - **`social` (required)** `string` - **`collection` (required)** `object` — Whether collection is ok, partial, paused, disconnected, unsupported or has never run. - **`cadence_hours` (required)** `integer` - **`last_collected_at` (required)** `string | null` - **`polling_window_days` (required)** `integer` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`state` (required)** `string` - **`coverage` (required)** `object | null` — How many posts and days the range actually rests on. - **`days_in_range` (required)** `integer` - **`days_with_posts` (required)** `integer` - **`posts_imported` (required)** `integer` - **`posts_in_range` (required)** `integer` - **`headline_metric` (required)** `string | null` — The key of the metric this platform leads with, if any. - **`interactions` (required)** `object | null` — The account's interaction score, whether the platform reports one natively, and what this range's score was built from. - **`change_pct` (required)** `number | null` - **`change_unit` (required)** `string` - **`components` (required)** `array` **Items:** `string` - **`definition` (required)** `string` - **`key` (required)** `string` - **`label` (required)** `string` - **`native` (required)** `boolean` - **`previous` (required)** `integer | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`source` (required)** `string` - **`status` (required)** `string` - **`value` (required)** `integer | null` - **`rates` (required)** `array` — Declared rates, each naming what it divided by. **Items:** - **`basis` (required)** `string` - **`change_pp` (required)** `number | null` - **`change_unit` (required)** `string` - **`definition` (required)** `string` - **`denominator_key` (required)** `string` - **`denominator_label` (required)** `string | null` - **`denominator_unit` (required)** `string | null` - **`key` (required)** `string` - **`label` (required)** `string` - **`numerator_key` (required)** `string` - **`per_post_mean` (required)** `number | null` - **`previous` (required)** `number | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`status` (required)** `string` - **`value` (required)** `number | null` - **`totals` (required)** `array` — Summed post metrics for the range, each against the previous window. **Items:** - **`change_pct` (required)** `number | null` - **`change_unit` (required)** `string` - **`key` (required)** `string` - **`label` (required)** `string` - **`previous` (required)** `integer | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`status` (required)** `string` - **`unit` (required)** `string` - **`value` (required)** `integer | null` **Example:** ```json { "data": [ { "account": { "id": 1, "social": "", "display_name": "", "handler": null, "avatar": null, "disconnected_at": null }, "collection": { "state": "", "reason": null, "remedy": null, "last_collected_at": null, "cadence_hours": 1, "polling_window_days": 1 }, "headline_metric": null, "totals": [ { "key": "", "label": "", "unit": "", "value": null, "previous": null, "change_pct": null, "change_unit": "", "status": "", "reason": null, "remedy": null } ], "interactions": { "key": "", "label": "", "definition": "", "native": true, "source": "", "components": [ "" ], "value": null, "previous": null, "change_pct": null, "change_unit": "", "status": "", "reason": null, "remedy": null }, "rates": [ { "key": "", "label": "", "definition": "", "numerator_key": "", "denominator_key": "", "denominator_label": null, "denominator_unit": null, "basis": "", "value": null, "per_post_mean": null, "previous": null, "change_pp": null, "change_unit": "", "status": "", "reason": null, "remedy": null } ], "coverage": { "posts_in_range": 1, "posts_imported": 1, "days_in_range": 1, "days_with_posts": 1 } } ] } ``` ##### Status: 401 Unauthenticated ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 403 Authorization error ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 404 Not found ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 422 Validation error ###### Content-Type: application/json - **`errors` (required)** `object` — A detailed description of each field that failed validation. - **`message` (required)** `string` — Errors overview. **Example:** ```json { "message": "", "errors": { "additionalProperty": [ "" ] } } ``` ### Get an account's analytics report - **Method:** `GET` - **Path:** `/spaces/{space}/accounts/{account}/analytics` - **Tags:** Analytics The full report for one connected account: its metric catalogue, totals, interaction score, rates, publish-date series, audience history and best times. Individual posts have their own endpoint. Defaults to the last 7 days in the space timezone. #### Parameters ##### `space` required - **In:** `path` The space ID `integer` ##### `account` required - **In:** `path` The account ID `integer` ##### `from` - **In:** `query` `string`, format: `date-time` ##### `to` - **In:** `query` `string`, format: `date-time` #### Responses ##### Status: 200 \`AccountReportResource\` ###### Content-Type: application/json - **`data` (required)** `object` - **`account` (required)** `object` — The account the report describes. - **`avatar` (required)** `string | null` - **`disconnected_at` (required)** `string | null` - **`display_name` (required)** `string` - **`handler` (required)** `string | null` - **`id` (required)** `integer` - **`social` (required)** `string` - **`audience` (required)** `object` — Account-level history — followers and every other declared account metric. - **`metrics` (required)** `array` **Items:** `string` - **`points` (required)** `array` **Items:** - **`date` (required)** `string` - **`values` (required)** `object` - **`supported` (required)** `boolean` - **`change`** `object` - **`labels`** `object` - **`latest`** `object | null` - **`date` (required)** `string` - **`values` (required)** `object` - **`basis` (required)** `object | null` — What the numbers are counted on, and whether the comparison cohort has had time to mature. - **`comparison_immature` (required)** `boolean` - **`note` (required)** `string` - **`series` (required)** `string` - **`values` (required)** `string` - **`best_times` (required)** `object | null` — The fixed 90-day day-and-hour grid. - **`best` (required)** `object | null` - **`average` (required)** `number` - **`hour` (required)** `integer` - **`posts` (required)** `integer` - **`weekday` (required)** `integer` - **`cells` (required)** `array` **Items:** - **`average` (required)** `number` - **`hour` (required)** `integer` - **`posts` (required)** `integer` - **`weekday` (required)** `integer` - **`lookback_days` (required)** `integer` - **`max_average` (required)** `number` - **`min_posts` (required)** `integer` - **`reason` (required)** `string | null` - **`status` (required)** `string` - **`timezone` (required)** `string` - **`collection` (required)** `object` — Whether collection is ok, partial, paused, disconnected, unsupported or has never run. - **`cadence_hours` (required)** `integer` - **`last_collected_at` (required)** `string | null` - **`polling_window_days` (required)** `integer` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`state` (required)** `string` - **`contract` (required)** `string` — The payload contract version, e.g. \`analytics.v1\`. The URL is never versioned. - **`coverage` (required)** `object | null` — How many posts and days the range actually rests on. - **`days_in_range` (required)** `integer` - **`days_with_posts` (required)** `integer` - **`posts_imported` (required)** `integer` - **`posts_in_range` (required)** `integer` - **`headline_metric` (required)** `string | null` — The key of the metric this platform leads with, if any. - **`interactions` (required)** `object | null` — The account's interaction score, whether the platform reports one natively, and what this range's score was built from. - **`change_pct` (required)** `number | null` - **`change_unit` (required)** `string` - **`components` (required)** `array` **Items:** `string` - **`definition` (required)** `string` - **`key` (required)** `string` - **`label` (required)** `string` - **`native` (required)** `boolean` - **`previous` (required)** `integer | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`source` (required)** `string` - **`status` (required)** `string` - **`value` (required)** `integer | null` - **`metrics` (required)** `array` — Every metric this platform declares, with its definition, unit and current health. **Items:** - **`accumulation` (required)** `string` - **`chartable` (required)** `boolean` - **`definition` (required)** `string` - **`headline` (required)** `boolean` - **`key` (required)** `string` - **`label` (required)** `string` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`role` (required)** `string` - **`scope` (required)** `string` - **`status` (required)** `string` - **`unit` (required)** `string` - **`window_days` (required)** `integer | null` - **`range` (required)** `object` — The reporting window, its timezone and the preceding comparison window. - **`days` (required)** `integer` - **`from` (required)** `string` - **`previous_from` (required)** `string` - **`previous_to` (required)** `string` - **`timezone` (required)** `string` - **`to` (required)** `string` - **`rates` (required)** `array` — Declared rates, each naming what it divided by. **Items:** - **`basis` (required)** `string` - **`change_pp` (required)** `number | null` - **`change_unit` (required)** `string` - **`definition` (required)** `string` - **`denominator_key` (required)** `string` - **`denominator_label` (required)** `string | null` - **`denominator_unit` (required)** `string | null` - **`key` (required)** `string` - **`label` (required)** `string` - **`numerator_key` (required)** `string` - **`per_post_mean` (required)** `number | null` - **`previous` (required)** `number | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`status` (required)** `string` - **`value` (required)** `number | null` - **`series` (required)** `object | null` — The daily publish-date cohort series. - **`basis` (required)** `string` - **`interval` (required)** `string` - **`metrics` (required)** `array` **Items:** `string` - **`note` (required)** `string` - **`points` (required)** `array` **Items:** - **`date` (required)** `string` - **`posts` (required)** `integer` - **`values` (required)** `object | null` - **`timezone` (required)** `string` - **`values` (required)** `string` - **`totals` (required)** `array` — Summed post metrics for the range, each against the previous window. **Items:** - **`change_pct` (required)** `number | null` - **`change_unit` (required)** `string` - **`key` (required)** `string` - **`label` (required)** `string` - **`previous` (required)** `integer | null` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`status` (required)** `string` - **`unit` (required)** `string` - **`value` (required)** `integer | null` **Example:** ```json { "data": { "contract": "", "account": { "id": 1, "social": "", "display_name": "", "handler": null, "avatar": null, "disconnected_at": null }, "range": { "from": "", "to": "", "timezone": "", "days": 1, "previous_from": "", "previous_to": "" }, "basis": { "series": "", "values": "", "note": "", "comparison_immature": true }, "collection": { "state": "", "reason": null, "remedy": null, "last_collected_at": null, "cadence_hours": 1, "polling_window_days": 1 }, "coverage": { "posts_in_range": 1, "posts_imported": 1, "days_in_range": 1, "days_with_posts": 1 }, "metrics": [ { "key": "", "label": "", "definition": "", "unit": "", "accumulation": "", "scope": "", "role": "", "window_days": null, "headline": true, "chartable": true, "status": "", "reason": null, "remedy": null } ], "headline_metric": null, "totals": [ { "key": "", "label": "", "unit": "", "value": null, "previous": null, "change_pct": null, "change_unit": "", "status": "", "reason": null, "remedy": null } ], "interactions": { "key": "", "label": "", "definition": "", "native": true, "source": "", "components": [ "" ], "value": null, "previous": null, "change_pct": null, "change_unit": "", "status": "", "reason": null, "remedy": null }, "rates": [ { "key": "", "label": "", "definition": "", "numerator_key": "", "denominator_key": "", "denominator_label": null, "denominator_unit": null, "basis": "", "value": null, "per_post_mean": null, "previous": null, "change_pp": null, "change_unit": "", "status": "", "reason": null, "remedy": null } ], "series": { "basis": "", "values": "", "note": "", "interval": "", "timezone": "", "metrics": [ "" ], "points": [ { "date": "", "posts": 1, "values": null } ] }, "audience": { "supported": true, "metrics": [ "" ], "points": [ { "date": "", "values": { "additionalProperty": 1 } } ], "labels": { "additionalProperty": "" }, "latest": { "date": "", "values": { "additionalProperty": 1 } }, "change": { "additionalProperty": 1 } }, "best_times": { "cells": [ { "weekday": 1, "hour": 1, "posts": 1, "average": 1 } ], "best": { "weekday": 1, "hour": 1, "posts": 1, "average": 1 }, "timezone": "", "lookback_days": 1, "min_posts": 1, "max_average": 1, "status": "", "reason": null } } } ``` ##### Status: 401 Unauthenticated ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 403 Authorization error ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 404 Not found ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 422 Validation error ###### Content-Type: application/json - **`errors` (required)** `object` — A detailed description of each field that failed validation. - **`message` (required)** `string` — Errors overview. **Example:** ```json { "message": "", "errors": { "additionalProperty": [ "" ] } } ``` ### List an account's posts with their metrics - **Method:** `GET` - **Path:** `/spaces/{space}/accounts/{account}/analytics/posts` - **Tags:** Analytics Every post the account published in the range, paginated, one row per post, with a column for each metric the platform declares. Order it by `sort` — `published_at`, `interactions` or any declared metric key — and `dir`; a key this account does not declare is a 422 naming the ones it does. Defaults to the last 7 days in the space timezone, newest first, 20 per page. #### Parameters ##### `space` required - **In:** `path` The space ID `integer` ##### `account` required - **In:** `path` The account ID `integer` ##### `from` - **In:** `query` `string`, format: `date-time` ##### `to` - **In:** `query` `string`, format: `date-time` ##### `sort` - **In:** `query` `string` ##### `dir` - **In:** `query` `string`, possible values: `"asc", "desc"` ##### `per_page` - **In:** `query` `integer` ##### `page` - **In:** `query` `integer` #### Responses ##### Status: 200 \`AccountPostsResource\` ###### Content-Type: application/json - **`account` (required)** `object` — The account whose posts these are. - **`avatar` (required)** `string | null` - **`disconnected_at` (required)** `string | null` - **`display_name` (required)** `string` - **`handler` (required)** `string | null` - **`id` (required)** `integer` - **`social` (required)** `string` - **`collection` (required)** `object` — Whether collection is ok, partial, paused, disconnected, unsupported or has never run. - **`cadence_hours` (required)** `integer` - **`last_collected_at` (required)** `string | null` - **`polling_window_days` (required)** `integer` - **`reason` (required)** `string | null` - **`remedy` (required)** `string | null` - **`state` (required)** `string` - **`columns` (required)** `array` — The metric columns this platform declares, in catalogue order, each with its own health. **Items:** - **`definition` (required)** `string` - **`headline` (required)** `boolean` - **`key` (required)** `string` - **`label` (required)** `string` - **`reason` (required)** `string | null` - **`status` (required)** `string` - **`unit` (required)** `string` - **`contract` (required)** `string` — The payload contract version, e.g. \`analytics.v1\`. Shared with the report; the URL is never versioned. - **`data` (required)** `array` — One row per post on this page. **Items:** - **`excerpt` (required)** `string` - **`imported` (required)** `boolean` - **`interactions` (required)** `object` - **`components` (required)** `object | null` - **`reason` (required)** `string | null` - **`source` (required)** `string` - **`status` (required)** `string` - **`total` (required)** `integer | null` - **`metrics` (required)** `object` - **`permalink` (required)** `string | null` - **`post_id` (required)** `integer` - **`published_at` (required)** `string | null` - **`thumbnail` (required)** `string | null` - **`meta` (required)** `object` — Where this page sits in the range's posts. - **`current_page` (required)** `integer` - **`last_page` (required)** `integer` - **`per_page` (required)** `integer` - **`total` (required)** `integer` - **`range` (required)** `object` — The window the posts were published in, and its timezone. - **`days` (required)** `integer` - **`from` (required)** `string` - **`previous_from` (required)** `string` - **`previous_to` (required)** `string` - **`timezone` (required)** `string` - **`to` (required)** `string` - **`sort` (required)** `object` — The ordering that was applied, and every key this account can be ordered by. - **`direction` (required)** `string` - **`key` (required)** `string` - **`options` (required)** `array` **Items:** - **`key` (required)** `string` - **`label` (required)** `string` - **`reason` (required)** `string | null` - **`sortable` (required)** `boolean` **Example:** ```json { "contract": "", "account": { "id": 1, "social": "", "display_name": "", "handler": null, "avatar": null, "disconnected_at": null }, "range": { "from": "", "to": "", "timezone": "", "days": 1, "previous_from": "", "previous_to": "" }, "collection": { "state": "", "reason": null, "remedy": null, "last_collected_at": null, "cadence_hours": 1, "polling_window_days": 1 }, "sort": { "key": "", "direction": "", "options": [ { "key": "", "label": "", "sortable": true, "reason": null } ] }, "columns": [ { "key": "", "label": "", "definition": "", "unit": "", "headline": true, "status": "", "reason": null } ], "data": [ { "post_id": 1, "published_at": null, "permalink": null, "imported": true, "excerpt": "", "thumbnail": null, "metrics": { "additionalProperty": { "value": null, "status": "", "reason": null } }, "interactions": { "total": null, "source": "", "components": null, "status": "", "reason": null } } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 1, "total": 1 } } ``` ##### Status: 401 Unauthenticated ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 403 Authorization error ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 404 Not found ###### Content-Type: application/json - **`message` (required)** `string` — Error overview. **Example:** ```json { "message": "" } ``` ##### Status: 422 Validation error ###### Content-Type: application/json - **`errors` (required)** `object` — A detailed description of each field that failed validation. - **`message` (required)** `string` — Errors overview. **Example:** ```json { "message": "", "errors": { "additionalProperty": [ "" ] } } ```