Insights - Swonkie API

Insights gives you direct access to the raw data behind Swonkie’s insights, metrics and dashboards. You can retrieve daily metrics such as followers, detailed lists of posts and engagement data like interactions, for both your own profiles and tracked competitors.

This focuses exclusively on data access. It does not support managing dashboards or widgets, nor does it provide calculated or composite metrics such as interaction rate. Instead, it exposes the foundational raw data used by Swonkie’s application, giving you full flexibility to store, transform and analyse the data according to your own needs and workflows.

Metrics Concept

Swonkie’s Insights feature is built on a powerful internal metrics system designed to support fast metric rollout and safe deprecation without compromising usability, stability or performance. Because of this architecture, the API exposes all available metrics across all supported sources and social networks currently implemented in Swonkie.

This approach ensures that developers always have access to the same foundational data used by the Swonkie application, even as metrics evolve over time.

Metric Types

There are two main categories of metrics:

Daily Metrics

Daily metrics are tracked on a per day basis and are expected to have historical values and day to day variation. If a specific day or metric value is missing, it usually indicates an issue, as daily metrics are expected to be continuously collected.

Post Metrics

Post metrics are associated with post entities and represent lifetime values. While they may be updated daily, they do not provide time based historical breakdowns. Each post contains multiple metrics that reflect its cumulative performance over time.

Although daily metrics are associated with dates and post metrics are associated with entities, all metrics follow the same definition pattern in the API.

Metric Definition

Each metric includes the following fields:

`metric`

A unique metric code.
You can find available metric codes in the metric documentation for each source. Only metrics explicitly marked as API supported are available through the API.

`type`

Defines the data type of the metric. Possible values are:

NUMBER: Numeric value
STRING: Text value
BREAKDOWN: Object with key value pairs. Some metrics may return a generic object
IMAGE: URL pointing to an image resource
URL: URL value
DATE: Date value in ISO 8601 format

Metric Deprecation Handling

Metrics are available by default, but since metrics can be deprecated over time, the API includes a notes section in metric responses to help you identify and handle these changes safely.

Deprecated Metrics

Provides information about metrics that are no longer active:

message
General information about the deprecation
metrics
Array of deprecated metrics, each containing:
- metric: Deprecated metric code
- deprecatedAt: Date of deprecation in ISO 8601 format
- deprecationArticle: Link to the related documentation article

Future Deprecated Metrics

Provides advance notice of metrics planned for deprecation, following the same structure as deprecated metrics. This allows you to prepare integrations ahead of time without disruption.

This metrics behaviour is designed to help developers work confidently in a constantly evolving data environment, while maintaining stability and getting the most value from the data provided by Swonkie.