staqlydocs
REST APIAPI referenceAnalytics

The workspace's publishing analytics for a range of days

The workspace's publishing analytics for a range of days (posts:read)

Every request sends Authorization: Bearer ...: the access token in local mode, an API key stk_... in cloud mode. Use Send to try it against your cloud instance with your API key.

GET
/v1/analytics

Aggregated from the workspace's own posts and targets; platform numbers (views, likes...) are the ones already cached on published targets (GET /v1/posts/{id}/metrics reads them, your automation reports its own), so this never calls a platform. from and to are days in the workspace's time zone, both included (default: the last 30 days up to today; at most 366 days). previous holds the same totals for the period of the same length right before, for comparisons. queue is what waits now. sources ignores the source filter so sources can be compared; feedback ignores channel. A target's outcome time is when it was published, or for a failed one when it failed.

Authorization

headerAuthorizationBearer <token>

API key (stk_...), or in the Community Edition the access token (stk_local_...)

Query Parameters

from?string

First day, YYYY-MM-DD in the workspace's time zone

Formatdate
to?string

Last day (included), YYYY-MM-DD; default today

Formatdate
days?integer

Instead of from: the last n days up to to (7, 30, 90...)

Range1 <= value <= 366
channel?string

Only this channel's targets

collection?string

Only posts of this collection

source?string

Only posts from this source, as sources[].source names it (dashboard, an agent's name, schedule:, repeat)

Response Body

OK

application/json
  1. response
range*
totals*
previous*
queue*

What waits now (not a period figure)

daily*array<>

Every day of the range, in the workspace's time zone

channels*array<>

Every channel of the workspace (or the filtered one), busiest first

sources*array<>

Where posts come from, most active first; ignores the source filter

posting_times*
top_posts*
failures*array<>

The most common failure reasons; errors that differ only by numbers, ids or links count as one

Itemsitems <= 10
feedback*

Preview comment threads (ignores the channel filter)

Example Request
curl -X GET 'https://staqly.example.com/v1/analytics'
Example Response
{  "range": {    "from": "2019-08-24",    "to": "2019-08-24",    "days": 1,    "timezone": "string",    "start": "2019-08-24T14:15:22Z",    "end": "2019-08-24T14:15:22Z",    "previous_from": "2019-08-24",    "previous_to": "2019-08-24"  },  "totals": {    "posts_created": 0,    "posts_published": 0,    "targets_published": 0,    "targets_failed": 0,    "success_rate": 0,    "retried": 0,    "delay_avg_seconds": 0,    "delay_p90_seconds": 0,    "metrics": {      "impressions": 0,      "engagements": 0,      "likes": 0,      "replies": 0,      "reposts": 0,      "quotes": 0,      "bookmarks": 0,      "link_clicks": 0    }  },  "previous": {    "posts_created": 0,    "posts_published": 0,    "targets_published": 0,    "targets_failed": 0,    "success_rate": 0,    "retried": 0,    "delay_avg_seconds": 0,    "delay_p90_seconds": 0,    "metrics": {      "impressions": 0,      "engagements": 0,      "likes": 0,      "replies": 0,      "reposts": 0,      "quotes": 0,      "bookmarks": 0,      "link_clicks": 0    }  },  "queue": {    "scheduled": 0,    "drafts": 0,    "next_publish_at": "2019-08-24T14:15:22Z"  },  "daily": [    {      "date": "2019-08-24",      "published": 0,      "failed": 0    }  ],  "channels": [    {      "channel_id": "string",      "name": "string",      "provider": "string",      "handle": "string",      "avatar_url": "string",      "status": "connected",      "published": 0,      "failed": 0,      "success_rate": 0,      "last_published_at": "2019-08-24T14:15:22Z",      "top_failure": "string",      "metrics": {        "impressions": 0,        "engagements": 0,        "likes": 0,        "replies": 0,        "reposts": 0,        "quotes": 0,        "bookmarks": 0,        "link_clicks": 0      },      "avg_engagements": 0,      "metrics_coverage": {        "support": "platform",        "published": 0,        "with_data": 0,        "updated_at": "2019-08-24T14:15:22Z"      }    }  ],  "sources": [    {      "source": "string",      "kind": "dashboard",      "label": "string",      "posts_created": 0,      "posts_published": 0,      "targets_published": 0,      "targets_failed": 0,      "success_rate": 0    }  ],  "posting_times": {    "cells": [      {        "weekday": 0,        "hour": 0,        "published": 0,        "samples": 0,        "avg_engagements": 0,        "low_confidence": true      }    ],    "best": [      {        "weekday": 0,        "hour": 0,        "published": 0,        "samples": 0,        "avg_engagements": 0,        "low_confidence": true      }    ],    "min_samples": 0  },  "top_posts": {    "by": "engagements",    "posts": [      {        "post_id": "string",        "excerpt": "string",        "published_at": "2019-08-24T14:15:22Z",        "channels": [          {            "channel_id": "string",            "provider": "string",            "external_url": "string"          }        ],        "metrics": {          "impressions": 0,          "engagements": 0,          "likes": 0,          "replies": 0,          "reposts": 0,          "quotes": 0,          "bookmarks": 0,          "link_clicks": 0        }      }    ]  },  "failures": [    {      "reason": "string",      "count": 1,      "channels": [        "string"      ],      "last_at": "2019-08-24T14:15:22Z",      "sample_post_id": "string"    }  ],  "feedback": {    "opened": 0,    "resolved": 0,    "open": 0  }}

Analytics

What staqly knows about the workspace's publishing (outcomes, automation sources, posting times) and the platform numbers already cached on posts

Webhooks

Outgoing webhooks and their deliveries. Delivery is at-least-once and not ordered (deliveries run in parallel and retry): receivers deduplicate on the event `id` (`X-Staqly-Event-Id`) and order by its `created_at`; the body has no `seq`. See https://docs.staqly.ai/automation/webhooks#delivery-guarantees