late-sdk 0.0.612 → 0.0.614
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +5 -0
- data/docs/AnalyticsApi.md +78 -2
- data/docs/FacebookPostEarningsResponse.md +32 -0
- data/docs/FacebookPostEarningsResponseMetricsValue.md +22 -0
- data/docs/FacebookPostEarningsResponseUnavailableMetricsInner.md +22 -0
- data/docs/InstagramAccountInsightsResponse.md +3 -1
- data/docs/InstagramAccountInsightsResponseMetricsValue.md +6 -2
- data/docs/InstagramAccountInsightsResponseUnavailableMetricsInner.md +22 -0
- data/docs/LinkedInAdsPlatformDataThoughtLeader.md +1 -1
- data/lib/zernio-sdk/api/analytics_api.rb +76 -2
- data/lib/zernio-sdk/models/facebook_post_earnings_response.rb +253 -0
- data/lib/zernio-sdk/models/facebook_post_earnings_response_metrics_value.rb +203 -0
- data/lib/zernio-sdk/models/facebook_post_earnings_response_unavailable_metrics_inner.rb +202 -0
- data/lib/zernio-sdk/models/instagram_account_insights_response.rb +14 -2
- data/lib/zernio-sdk/models/instagram_account_insights_response_metrics_value.rb +60 -5
- data/lib/zernio-sdk/models/instagram_account_insights_response_unavailable_metrics_inner.rb +202 -0
- data/lib/zernio-sdk/models/linked_in_ads_platform_data_thought_leader.rb +2 -2
- data/lib/zernio-sdk/version.rb +1 -1
- data/lib/zernio-sdk.rb +4 -0
- data/openapi.yaml +341 -18
- data/spec/api/analytics_api_spec.rb +15 -1
- data/spec/models/facebook_post_earnings_response_metrics_value_spec.rb +52 -0
- data/spec/models/facebook_post_earnings_response_spec.rb +82 -0
- data/spec/models/facebook_post_earnings_response_unavailable_metrics_inner_spec.rb +52 -0
- data/spec/models/instagram_account_insights_response_metrics_value_spec.rb +16 -0
- data/spec/models/instagram_account_insights_response_spec.rb +6 -0
- data/spec/models/instagram_account_insights_response_unavailable_metrics_inner_spec.rb +52 -0
- data/zernio-sdk-0.0.614.gem +0 -0
- metadata +19 -3
- data/zernio-sdk-0.0.612.gem +0 -0
data/openapi.yaml
CHANGED
|
@@ -1871,6 +1871,14 @@ components:
|
|
|
1871
1871
|
description: |
|
|
1872
1872
|
Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
|
|
1873
1873
|
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).
|
|
1874
|
+
|
|
1875
|
+
Monetary metrics additionally carry "unit" and "currency". Zernio never rescales money:
|
|
1876
|
+
"total" and every "values[].value" are the platform's raw numbers in the stated unit.
|
|
1877
|
+
Monetary metrics also keep "values" on metricType=total_value, because their "total" is the
|
|
1878
|
+
sum of the daily buckets the platform returned over the range: keep the series so you can
|
|
1879
|
+
reconcile that sum against the platform's own reporting before invoicing on it.
|
|
1880
|
+
A metric that could not be served is absent from this object and listed in
|
|
1881
|
+
"unavailableMetrics" instead, so an unavailable metric is never reported as a zero.
|
|
1874
1882
|
additionalProperties:
|
|
1875
1883
|
type: object
|
|
1876
1884
|
properties:
|
|
@@ -1879,7 +1887,7 @@ components:
|
|
|
1879
1887
|
description: Sum or aggregate value for the metric
|
|
1880
1888
|
values:
|
|
1881
1889
|
type: array
|
|
1882
|
-
description: Daily values (
|
|
1890
|
+
description: Daily values (for time_series, and always on monetary metrics)
|
|
1883
1891
|
items:
|
|
1884
1892
|
type: object
|
|
1885
1893
|
properties:
|
|
@@ -1898,9 +1906,149 @@ components:
|
|
|
1898
1906
|
type: string
|
|
1899
1907
|
value:
|
|
1900
1908
|
type: number
|
|
1909
|
+
unit:
|
|
1910
|
+
type: string
|
|
1911
|
+
enum: [micro_amount, unspecified]
|
|
1912
|
+
description: |
|
|
1913
|
+
Present on monetary metrics only. The scale of "total" and of every "values[].value",
|
|
1914
|
+
exactly as the platform returned them.
|
|
1915
|
+
|
|
1916
|
+
"micro_amount": the platform returned an object shape carrying a micro amount, and the
|
|
1917
|
+
values are that integer, summed, unconverted. Zernio does not publish a divisor because
|
|
1918
|
+
Meta does not document one; divide by the scale you have verified against the Page's own
|
|
1919
|
+
Meta Business Suite export. On Facebook Page insights this is always
|
|
1920
|
+
content_monetization_earnings.
|
|
1921
|
+
|
|
1922
|
+
"unspecified": the platform returned a bare number with no unit metadata. It is passed
|
|
1923
|
+
through as-is; the platform does not state whether it is major or minor currency units.
|
|
1924
|
+
On Facebook Page insights this is always monetization_approximate_earnings.
|
|
1925
|
+
currency:
|
|
1926
|
+
type: [string, "null"]
|
|
1927
|
+
description: |
|
|
1928
|
+
ISO 4217 currency of a monetary metric, or null when the platform omitted it.
|
|
1929
|
+
Always null on monetization_approximate_earnings, which Meta returns as a bare number
|
|
1930
|
+
with no currency; always present on content_monetization_earnings.
|
|
1931
|
+
example: "USD"
|
|
1932
|
+
unavailableMetrics:
|
|
1933
|
+
type: array
|
|
1934
|
+
description: |
|
|
1935
|
+
Requested metrics that could not be served. Present only when at least one metric is
|
|
1936
|
+
unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than
|
|
1937
|
+
reported as 0, which is how an unavailable metric is distinguished from a genuine zero.
|
|
1938
|
+
The request itself still succeeds with HTTP 200.
|
|
1939
|
+
items:
|
|
1940
|
+
type: object
|
|
1941
|
+
properties:
|
|
1942
|
+
metric:
|
|
1943
|
+
type: string
|
|
1944
|
+
description: The requested metric name.
|
|
1945
|
+
reason:
|
|
1946
|
+
type: string
|
|
1947
|
+
enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error]
|
|
1948
|
+
description: |
|
|
1949
|
+
"not_enrolled": the account is not enrolled in the program behind this metric.
|
|
1950
|
+
"permission_missing": the connected user lacks access to this metric.
|
|
1951
|
+
"unsupported_metric": the platform does not accept this metric name on the API version Zernio uses.
|
|
1952
|
+
"no_data": the platform returned no bucket for this metric over the requested range.
|
|
1953
|
+
"unreadable_value": the platform returned a value shape Zernio cannot read, so no total is reported.
|
|
1954
|
+
"mixed_currency": readable values disagree on currency or unit within the range.
|
|
1955
|
+
"upstream_error": any other platform failure.
|
|
1956
|
+
|
|
1957
|
+
"no_data" is the common case in practice. The others are defensive: "not_enrolled" and
|
|
1958
|
+
"unsupported_metric" in particular have not been observed on live Facebook traffic, since
|
|
1959
|
+
a non-enrolled Page returns zeros rather than an error and metric names are validated
|
|
1960
|
+
before any platform call.
|
|
1961
|
+
message:
|
|
1962
|
+
type: string
|
|
1963
|
+
description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.'
|
|
1901
1964
|
dataDelay:
|
|
1902
1965
|
type: string
|
|
1903
1966
|
example: "Data may be delayed up to 48 hours"
|
|
1967
|
+
FacebookPostEarningsResponse:
|
|
1968
|
+
type: object
|
|
1969
|
+
description: |
|
|
1970
|
+
Lifetime monetization earnings for one Facebook post. Same "unit" / "currency" contract and
|
|
1971
|
+
same unavailable-vs-zero contract as the Page-level response; there is no date range, no
|
|
1972
|
+
metricType, and no daily "values", because the single lifetime bucket IS the total.
|
|
1973
|
+
properties:
|
|
1974
|
+
success:
|
|
1975
|
+
type: boolean
|
|
1976
|
+
example: true
|
|
1977
|
+
accountId:
|
|
1978
|
+
type: string
|
|
1979
|
+
example: "64e1a2b3c4d5e6f7a8b9c0d1"
|
|
1980
|
+
postId:
|
|
1981
|
+
type: string
|
|
1982
|
+
description: 'The platform post ID that was queried, echoed back.'
|
|
1983
|
+
example: "123456789_987654321"
|
|
1984
|
+
platform:
|
|
1985
|
+
type: string
|
|
1986
|
+
example: "facebook"
|
|
1987
|
+
period:
|
|
1988
|
+
type: string
|
|
1989
|
+
enum: [lifetime]
|
|
1990
|
+
description: |
|
|
1991
|
+
Always "lifetime": the total is cumulative since publication and must not be summed
|
|
1992
|
+
across dates or across posts.
|
|
1993
|
+
metrics:
|
|
1994
|
+
type: object
|
|
1995
|
+
description: |
|
|
1996
|
+
One entry per served metric. A metric reported here with "total": 0 genuinely earned
|
|
1997
|
+
nothing (or its Page is not enrolled, which Meta reports identically).
|
|
1998
|
+
additionalProperties:
|
|
1999
|
+
type: object
|
|
2000
|
+
properties:
|
|
2001
|
+
total:
|
|
2002
|
+
type: number
|
|
2003
|
+
description: 'Lifetime earnings in "unit", exactly as Meta returned them. Never rescaled.'
|
|
2004
|
+
unit:
|
|
2005
|
+
type: string
|
|
2006
|
+
enum: [micro_amount, unspecified]
|
|
2007
|
+
description: |
|
|
2008
|
+
"micro_amount": Meta returned an object shape carrying a micro amount, and "total" is
|
|
2009
|
+
that integer, unconverted. Zernio does not publish a divisor because Meta does not
|
|
2010
|
+
document one; divide by the scale you have verified against the Page's own Meta
|
|
2011
|
+
Business Suite export. This is always content_monetization_earnings.
|
|
2012
|
+
|
|
2013
|
+
"unspecified": Meta returned a bare number with no unit metadata, passed through as-is;
|
|
2014
|
+
Meta does not state whether it is major or minor currency units. This is always
|
|
2015
|
+
monetization_approximate_earnings.
|
|
2016
|
+
currency:
|
|
2017
|
+
type: [string, "null"]
|
|
2018
|
+
description: |
|
|
2019
|
+
ISO 4217 currency, or null when Meta omitted it. Always null on
|
|
2020
|
+
monetization_approximate_earnings; always present on content_monetization_earnings.
|
|
2021
|
+
example: "USD"
|
|
2022
|
+
unavailableMetrics:
|
|
2023
|
+
type: array
|
|
2024
|
+
description: |
|
|
2025
|
+
Requested metrics Meta could not serve. Present only when at least one metric is
|
|
2026
|
+
unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than
|
|
2027
|
+
reported as 0. The request itself still succeeds with HTTP 200.
|
|
2028
|
+
items:
|
|
2029
|
+
type: object
|
|
2030
|
+
properties:
|
|
2031
|
+
metric:
|
|
2032
|
+
type: string
|
|
2033
|
+
description: The requested metric name.
|
|
2034
|
+
reason:
|
|
2035
|
+
type: string
|
|
2036
|
+
enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error]
|
|
2037
|
+
description: |
|
|
2038
|
+
"not_enrolled": the account is not enrolled in the program behind this metric.
|
|
2039
|
+
"permission_missing": the connected user lacks access to this metric.
|
|
2040
|
+
"unsupported_metric": Meta does not accept this metric name on the API version Zernio uses.
|
|
2041
|
+
"no_data": Meta returned no bucket for this metric.
|
|
2042
|
+
"unreadable_value": Meta returned a value shape Zernio cannot read, so no total is reported.
|
|
2043
|
+
"mixed_currency": readable values disagree on currency or unit.
|
|
2044
|
+
"upstream_error": any other platform failure.
|
|
2045
|
+
|
|
2046
|
+
"no_data" is the common case in practice; the others are defensive.
|
|
2047
|
+
message:
|
|
2048
|
+
type: string
|
|
2049
|
+
description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.'
|
|
2050
|
+
dataDelay:
|
|
2051
|
+
type: string
|
|
1904
2052
|
InstagramDemographicsResponse:
|
|
1905
2053
|
type: object
|
|
1906
2054
|
properties:
|
|
@@ -4780,15 +4928,18 @@ components:
|
|
|
4780
4928
|
additionalProperties: false
|
|
4781
4929
|
required: [postUrn]
|
|
4782
4930
|
description: |
|
|
4783
|
-
POST /v1/ads/create only.
|
|
4784
|
-
|
|
4785
|
-
|
|
4786
|
-
|
|
4787
|
-
|
|
4788
|
-
|
|
4789
|
-
|
|
4790
|
-
|
|
4791
|
-
|
|
4931
|
+
POST /v1/ads/create only. Sponsors an existing LinkedIn post
|
|
4932
|
+
(a share or ugcPost authored by your organization's Company
|
|
4933
|
+
Page) as the creative, keeping its commentary, author and
|
|
4934
|
+
engagement. Unlike boostPost, which provisions its own
|
|
4935
|
+
CampaignGroup + Campaign around the post, this variant
|
|
4936
|
+
attaches the reference under the campaign /v1/ads/create
|
|
4937
|
+
builds — same shape as every other format, so the caller can
|
|
4938
|
+
pick bidding / targeting / schedule freely. No headline, body,
|
|
4939
|
+
imageUrl or organization are needed; the referenced post
|
|
4940
|
+
carries its own commentary and author. Mutually exclusive
|
|
4941
|
+
with the other creative sources. Posts from personal profiles
|
|
4942
|
+
(Thought Leader Ads) are NOT supported (see postUrn).
|
|
4792
4943
|
properties:
|
|
4793
4944
|
postUrn:
|
|
4794
4945
|
type: string
|
|
@@ -4798,13 +4949,13 @@ components:
|
|
|
4798
4949
|
urn:li:ugcPost:N. Get it via "Copy link to post" on the
|
|
4799
4950
|
target LinkedIn post (the URL contains -share- for a share
|
|
4800
4951
|
or -ugcPost- for a ugcPost, then the numeric id).
|
|
4801
|
-
|
|
4802
|
-
|
|
4803
|
-
|
|
4804
|
-
regardless of sponsorship approval
|
|
4805
|
-
|
|
4806
|
-
|
|
4807
|
-
|
|
4952
|
+
The post must be authored by an organization (Company
|
|
4953
|
+
Page). Member (personal profile) posts, i.e. Thought
|
|
4954
|
+
Leader Ads proper, are rejected by LinkedIn's public
|
|
4955
|
+
Marketing API regardless of sponsorship approval and of
|
|
4956
|
+
post type (a LinkedIn limitation; their Campaign Manager
|
|
4957
|
+
creates those through a private API). Referencing a
|
|
4958
|
+
member post returns a 422 with a clear error.
|
|
4808
4959
|
description: >
|
|
4809
4960
|
LinkedIn-specific options for POST /v1/ads/boost and POST /v1/ads/create:
|
|
4810
4961
|
campaign bidding and delivery controls, plus the LinkedIn-only creative
|
|
@@ -9346,6 +9497,31 @@ paths:
|
|
|
9346
9497
|
left by the page_fan_adds / page_fan_removes deprecation):
|
|
9347
9498
|
- followers_gained
|
|
9348
9499
|
- followers_lost
|
|
9500
|
+
|
|
9501
|
+
Monetization (opt-in, not in the defaults):
|
|
9502
|
+
- content_monetization_earnings
|
|
9503
|
+
- monetization_approximate_earnings
|
|
9504
|
+
|
|
9505
|
+
Each monetization metric is fetched with its own separate Graph call, so requesting both
|
|
9506
|
+
adds two calls. Values are approximate and Meta restates them after the fact.
|
|
9507
|
+
|
|
9508
|
+
content_monetization_earnings returns an object per day and always carries unit
|
|
9509
|
+
"micro_amount" plus an ISO 4217 "currency". monetization_approximate_earnings returns a bare
|
|
9510
|
+
number per day, so its unit is always "unspecified" and its "currency" is always null. The two
|
|
9511
|
+
are on different scales and are not comparable to each other. Both keep their daily "values"
|
|
9512
|
+
on every metricType and are never rescaled by Zernio.
|
|
9513
|
+
|
|
9514
|
+
Earnings here are Page-level daily buckets and "total" is their sum. Meta does not
|
|
9515
|
+
document whether a bucket carries that day's earnings or a running total, and every
|
|
9516
|
+
Page measured so far earned exactly 0, so reconcile "total" against the Page's own Meta
|
|
9517
|
+
export before relying on it; the daily "values" are always returned for that purpose.
|
|
9518
|
+
Per-post lifetime earnings are served by GET /v1/analytics/facebook/post-earnings.
|
|
9519
|
+
|
|
9520
|
+
A Page that is not enrolled in monetization, or that earned nothing, returns normal daily
|
|
9521
|
+
buckets of 0 in "metrics": Meta does not distinguish the two, so a 0 total here does NOT mean
|
|
9522
|
+
the Page is enrolled. "unavailableMetrics" covers the narrower case where Meta returned no
|
|
9523
|
+
bucket for the metric at all ("no_data") or rejected the request outright, and the metric is
|
|
9524
|
+
then omitted from "metrics" rather than reported as 0.
|
|
9349
9525
|
- name: since
|
|
9350
9526
|
in: query
|
|
9351
9527
|
schema: { type: string, format: date }
|
|
@@ -9395,7 +9571,49 @@ paths:
|
|
|
9395
9571
|
values:
|
|
9396
9572
|
- { date: "2026-03-01", value: 1 }
|
|
9397
9573
|
- { date: "2026-03-02", value: 0 }
|
|
9398
|
-
dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names."
|
|
9574
|
+
dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
|
|
9575
|
+
monetization:
|
|
9576
|
+
summary: 'Both monetization metrics, each at its own scale'
|
|
9577
|
+
value:
|
|
9578
|
+
success: true
|
|
9579
|
+
accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
|
|
9580
|
+
platform: "facebook"
|
|
9581
|
+
dateRange: { since: "2026-06-01", until: "2026-06-30" }
|
|
9582
|
+
metricType: "total_value"
|
|
9583
|
+
metrics:
|
|
9584
|
+
page_media_view:
|
|
9585
|
+
total: 125000
|
|
9586
|
+
content_monetization_earnings:
|
|
9587
|
+
total: 1234000000
|
|
9588
|
+
unit: "micro_amount"
|
|
9589
|
+
currency: "USD"
|
|
9590
|
+
values:
|
|
9591
|
+
- { date: "2026-06-01", value: 634000000 }
|
|
9592
|
+
- { date: "2026-06-02", value: 600000000 }
|
|
9593
|
+
monetization_approximate_earnings:
|
|
9594
|
+
total: 1234
|
|
9595
|
+
unit: "unspecified"
|
|
9596
|
+
currency: null
|
|
9597
|
+
values:
|
|
9598
|
+
- { date: "2026-06-01", value: 700 }
|
|
9599
|
+
- { date: "2026-06-02", value: 534 }
|
|
9600
|
+
dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
|
|
9601
|
+
monetizationUnavailable:
|
|
9602
|
+
summary: 'A monetization metric Meta returned no bucket for'
|
|
9603
|
+
value:
|
|
9604
|
+
success: true
|
|
9605
|
+
accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
|
|
9606
|
+
platform: "facebook"
|
|
9607
|
+
dateRange: { since: "2026-06-01", until: "2026-06-30" }
|
|
9608
|
+
metricType: "total_value"
|
|
9609
|
+
metrics:
|
|
9610
|
+
page_media_view:
|
|
9611
|
+
total: 125000
|
|
9612
|
+
unavailableMetrics:
|
|
9613
|
+
- metric: "content_monetization_earnings"
|
|
9614
|
+
reason: "no_data"
|
|
9615
|
+
message: "Meta returned no data for this monetization metric."
|
|
9616
|
+
dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
|
|
9399
9617
|
'400':
|
|
9400
9618
|
description: |
|
|
9401
9619
|
Bad request. Common cases:
|
|
@@ -9409,6 +9627,111 @@ paths:
|
|
|
9409
9627
|
'404':
|
|
9410
9628
|
description: Account not found
|
|
9411
9629
|
|
|
9630
|
+
/v1/analytics/facebook/post-earnings:
|
|
9631
|
+
get:
|
|
9632
|
+
operationId: getFacebookPostEarnings
|
|
9633
|
+
tags: [Analytics]
|
|
9634
|
+
summary: Get Facebook post monetization earnings
|
|
9635
|
+
description: |
|
|
9636
|
+
Returns lifetime monetization earnings for ONE Facebook post, read live from Meta on every
|
|
9637
|
+
request. Requires the Analytics add-on.
|
|
9638
|
+
|
|
9639
|
+
Earnings are CUMULATIVE since the post was published, not earnings within a date range, so
|
|
9640
|
+
this endpoint takes no since/until and the totals must not be summed across dates or across
|
|
9641
|
+
posts. Page-level daily earnings live on /v1/analytics/facebook/page-insights.
|
|
9642
|
+
|
|
9643
|
+
A post on a Page that is not enrolled in monetization, or that earned nothing, returns
|
|
9644
|
+
"total": 0 rather than an error: Meta does not distinguish the two. A metric Meta returned no
|
|
9645
|
+
bucket for at all is reported in "unavailableMetrics" and omitted from "metrics", never as a 0.
|
|
9646
|
+
|
|
9647
|
+
Amounts are the platform's raw numbers in the stated "unit" and are never rescaled by Zernio.
|
|
9648
|
+
Breakdown dimensions are not exposed and a "breakdown" param is rejected with 400. So are
|
|
9649
|
+
"since", "until", "period", and "metricType": scoping this endpoint to a window is not
|
|
9650
|
+
possible, and silently returning the lifetime total for one would let a caller sum a year of
|
|
9651
|
+
weekly requests into a figure ~52x the post's real earnings.
|
|
9652
|
+
parameters:
|
|
9653
|
+
- name: accountId
|
|
9654
|
+
in: query
|
|
9655
|
+
required: true
|
|
9656
|
+
schema: { type: string }
|
|
9657
|
+
description: The Zernio SocialAccount ID for the connected Facebook Page.
|
|
9658
|
+
- name: postId
|
|
9659
|
+
in: query
|
|
9660
|
+
required: true
|
|
9661
|
+
schema: { type: string }
|
|
9662
|
+
description: |
|
|
9663
|
+
The platform post ID, exactly as returned in platformAnalytics[].platformPostId by
|
|
9664
|
+
/v1/analytics: "{pageId}_{postId}", or the bare video ID for Reels.
|
|
9665
|
+
- name: metrics
|
|
9666
|
+
in: query
|
|
9667
|
+
schema: { type: string }
|
|
9668
|
+
description: |
|
|
9669
|
+
Comma-separated list of monetization metrics. Defaults to both:
|
|
9670
|
+
- content_monetization_earnings
|
|
9671
|
+
- monetization_approximate_earnings
|
|
9672
|
+
|
|
9673
|
+
content_monetization_earnings always carries unit "micro_amount" plus an ISO 4217
|
|
9674
|
+
"currency". monetization_approximate_earnings is always a bare number, so its unit is
|
|
9675
|
+
"unspecified" and its "currency" is null. The two are on different scales and are not
|
|
9676
|
+
comparable to each other. Any other metric name is rejected with 400.
|
|
9677
|
+
responses:
|
|
9678
|
+
'200':
|
|
9679
|
+
description: Lifetime per-post monetization earnings
|
|
9680
|
+
content:
|
|
9681
|
+
application/json:
|
|
9682
|
+
schema:
|
|
9683
|
+
$ref: '#/components/schemas/FacebookPostEarningsResponse'
|
|
9684
|
+
examples:
|
|
9685
|
+
served:
|
|
9686
|
+
summary: 'Both metrics served, each at its own scale'
|
|
9687
|
+
value:
|
|
9688
|
+
success: true
|
|
9689
|
+
accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
|
|
9690
|
+
postId: "123456789_987654321"
|
|
9691
|
+
platform: "facebook"
|
|
9692
|
+
period: "lifetime"
|
|
9693
|
+
metrics:
|
|
9694
|
+
content_monetization_earnings:
|
|
9695
|
+
total: 1234000000
|
|
9696
|
+
unit: "micro_amount"
|
|
9697
|
+
currency: "USD"
|
|
9698
|
+
monetization_approximate_earnings:
|
|
9699
|
+
total: 1234
|
|
9700
|
+
unit: "unspecified"
|
|
9701
|
+
currency: null
|
|
9702
|
+
dataDelay: "Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."
|
|
9703
|
+
partiallyUnavailable:
|
|
9704
|
+
summary: 'One metric served, one with no bucket returned by Meta'
|
|
9705
|
+
value:
|
|
9706
|
+
success: true
|
|
9707
|
+
accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
|
|
9708
|
+
postId: "123456789_987654321"
|
|
9709
|
+
platform: "facebook"
|
|
9710
|
+
period: "lifetime"
|
|
9711
|
+
metrics:
|
|
9712
|
+
monetization_approximate_earnings:
|
|
9713
|
+
total: 0
|
|
9714
|
+
unit: "unspecified"
|
|
9715
|
+
currency: null
|
|
9716
|
+
unavailableMetrics:
|
|
9717
|
+
- metric: "content_monetization_earnings"
|
|
9718
|
+
reason: "no_data"
|
|
9719
|
+
message: "Meta returned no data for this monetization metric."
|
|
9720
|
+
dataDelay: "Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."
|
|
9721
|
+
'400':
|
|
9722
|
+
description: |
|
|
9723
|
+
Bad request. Common cases:
|
|
9724
|
+
- Invalid accountId format, or a metric name that is not a monetization metric
|
|
9725
|
+
- A "breakdown" param was supplied (breakdown dimensions are not exposed)
|
|
9726
|
+
- A "since", "until", "period", or "metricType" param was supplied (this endpoint returns a lifetime total and takes no date range)
|
|
9727
|
+
- Account has no Page access token (metadata.pageAccessToken missing)
|
|
9728
|
+
- Account is not a Facebook account
|
|
9729
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
9730
|
+
'402':
|
|
9731
|
+
description: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.
|
|
9732
|
+
'404':
|
|
9733
|
+
description: Account not found
|
|
9734
|
+
|
|
9412
9735
|
/v1/analytics/instagram/account-insights:
|
|
9413
9736
|
get:
|
|
9414
9737
|
operationId: getInstagramAccountInsights
|
|
@@ -107,7 +107,7 @@ describe 'AnalyticsApi' do
|
|
|
107
107
|
# Returns page-level Facebook insights (media views, views, post engagements, video metrics, follower counts). Response shape matches /v1/analytics/instagram/account-insights so the same client handling works across platforms. Metric names track the current (post-November 2025) Meta Graph API. The legacy page_impressions / page_fans / page_fan_adds / page_fan_removes metrics were deprecated by Meta on November 15, 2025 and are NOT accepted by this endpoint. Use the replacements below. Because Meta did not provide direct adds/removes replacements, Zernio synthesizes followers_gained / followers_lost from the daily follower snapshotter. Max 89 days, defaults to last 30 days. Requires the Analytics add-on.
|
|
108
108
|
# @param account_id The Zernio SocialAccount ID for the connected Facebook Page.
|
|
109
109
|
# @param [Hash] opts the optional parameters
|
|
110
|
-
# @option opts [String] :metrics Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\". Live Meta metrics (current names, post-Nov-2025): - page_media_view (replaces deprecated page_impressions) - page_views_total - page_post_engagements - page_video_views - page_video_view_time - page_follows (replaces deprecated page_fans) Zernio-synthesized from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation): - followers_gained - followers_lost
|
|
110
|
+
# @option opts [String] :metrics Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\". Live Meta metrics (current names, post-Nov-2025): - page_media_view (replaces deprecated page_impressions) - page_views_total - page_post_engagements - page_video_views - page_video_view_time - page_follows (replaces deprecated page_fans) Zernio-synthesized from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation): - followers_gained - followers_lost Monetization (opt-in, not in the defaults): - content_monetization_earnings - monetization_approximate_earnings Each monetization metric is fetched with its own separate Graph call, so requesting both adds two calls. Values are approximate and Meta restates them after the fact. content_monetization_earnings returns an object per day and always carries unit \"micro_amount\" plus an ISO 4217 \"currency\". monetization_approximate_earnings returns a bare number per day, so its unit is always \"unspecified\" and its \"currency\" is always null. The two are on different scales and are not comparable to each other. Both keep their daily \"values\" on every metricType and are never rescaled by Zernio. Earnings here are Page-level daily buckets and \"total\" is their sum. Meta does not document whether a bucket carries that day's earnings or a running total, and every Page measured so far earned exactly 0, so reconcile \"total\" against the Page's own Meta export before relying on it; the daily \"values\" are always returned for that purpose. Per-post lifetime earnings are served by GET /v1/analytics/facebook/post-earnings. A Page that is not enrolled in monetization, or that earned nothing, returns normal daily buckets of 0 in \"metrics\": Meta does not distinguish the two, so a 0 total here does NOT mean the Page is enrolled. \"unavailableMetrics\" covers the narrower case where Meta returned no bucket for the metric at all (\"no_data\") or rejected the request outright, and the metric is then omitted from \"metrics\" rather than reported as 0.
|
|
111
111
|
# @option opts [Date] :since Start date (YYYY-MM-DD). Defaults to 30 days ago.
|
|
112
112
|
# @option opts [Date] :_until End date (YYYY-MM-DD). Defaults to today.
|
|
113
113
|
# @option opts [String] :metric_type \"total_value\" (default) returns aggregated totals only. \"time_series\" returns daily values in the \"values\" array.
|
|
@@ -118,6 +118,20 @@ describe 'AnalyticsApi' do
|
|
|
118
118
|
end
|
|
119
119
|
end
|
|
120
120
|
|
|
121
|
+
# unit tests for get_facebook_post_earnings
|
|
122
|
+
# Get Facebook post monetization earnings
|
|
123
|
+
# Returns lifetime monetization earnings for ONE Facebook post, read live from Meta on every request. Requires the Analytics add-on. Earnings are CUMULATIVE since the post was published, not earnings within a date range, so this endpoint takes no since/until and the totals must not be summed across dates or across posts. Page-level daily earnings live on /v1/analytics/facebook/page-insights. A post on a Page that is not enrolled in monetization, or that earned nothing, returns \"total\": 0 rather than an error: Meta does not distinguish the two. A metric Meta returned no bucket for at all is reported in \"unavailableMetrics\" and omitted from \"metrics\", never as a 0. Amounts are the platform's raw numbers in the stated \"unit\" and are never rescaled by Zernio. Breakdown dimensions are not exposed and a \"breakdown\" param is rejected with 400. So are \"since\", \"until\", \"period\", and \"metricType\": scoping this endpoint to a window is not possible, and silently returning the lifetime total for one would let a caller sum a year of weekly requests into a figure ~52x the post's real earnings.
|
|
124
|
+
# @param account_id The Zernio SocialAccount ID for the connected Facebook Page.
|
|
125
|
+
# @param post_id The platform post ID, exactly as returned in platformAnalytics[].platformPostId by /v1/analytics: \"{pageId}_{postId}\", or the bare video ID for Reels.
|
|
126
|
+
# @param [Hash] opts the optional parameters
|
|
127
|
+
# @option opts [String] :metrics Comma-separated list of monetization metrics. Defaults to both: - content_monetization_earnings - monetization_approximate_earnings content_monetization_earnings always carries unit \"micro_amount\" plus an ISO 4217 \"currency\". monetization_approximate_earnings is always a bare number, so its unit is \"unspecified\" and its \"currency\" is null. The two are on different scales and are not comparable to each other. Any other metric name is rejected with 400.
|
|
128
|
+
# @return [FacebookPostEarningsResponse]
|
|
129
|
+
describe 'get_facebook_post_earnings test' do
|
|
130
|
+
it 'should work' do
|
|
131
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
132
|
+
end
|
|
133
|
+
end
|
|
134
|
+
|
|
121
135
|
# unit tests for get_facebook_post_reactions
|
|
122
136
|
# Get Facebook post reactions
|
|
123
137
|
# Returns the reaction breakdown for a Facebook Page post: a count per reaction type plus the overall total. The whole breakdown is fetched in a single Graph call. Note that the post analytics endpoint reports only an aggregate reaction count (surfaced there as `likes`), so use this endpoint when you need per-type counts.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
=begin
|
|
2
|
+
#Zernio API
|
|
3
|
+
|
|
4
|
+
#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api
|
|
5
|
+
|
|
6
|
+
The version of the OpenAPI document: 1.0.4
|
|
7
|
+
Contact: support@zernio.com
|
|
8
|
+
Generated by: https://openapi-generator.tech
|
|
9
|
+
Generator version: 7.19.0
|
|
10
|
+
|
|
11
|
+
=end
|
|
12
|
+
|
|
13
|
+
require 'spec_helper'
|
|
14
|
+
require 'json'
|
|
15
|
+
require 'date'
|
|
16
|
+
|
|
17
|
+
# Unit tests for Zernio::FacebookPostEarningsResponseMetricsValue
|
|
18
|
+
# Automatically generated by openapi-generator (https://openapi-generator.tech)
|
|
19
|
+
# Please update as you see appropriate
|
|
20
|
+
describe Zernio::FacebookPostEarningsResponseMetricsValue do
|
|
21
|
+
#let(:instance) { Zernio::FacebookPostEarningsResponseMetricsValue.new }
|
|
22
|
+
|
|
23
|
+
describe 'test an instance of FacebookPostEarningsResponseMetricsValue' do
|
|
24
|
+
it 'should create an instance of FacebookPostEarningsResponseMetricsValue' do
|
|
25
|
+
# uncomment below to test the instance creation
|
|
26
|
+
#expect(instance).to be_instance_of(Zernio::FacebookPostEarningsResponseMetricsValue)
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
describe 'test attribute "total"' do
|
|
31
|
+
it 'should work' do
|
|
32
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
describe 'test attribute "unit"' do
|
|
37
|
+
it 'should work' do
|
|
38
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
39
|
+
# validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["micro_amount", "unspecified"])
|
|
40
|
+
# validator.allowable_values.each do |value|
|
|
41
|
+
# expect { instance.unit = value }.not_to raise_error
|
|
42
|
+
# end
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
describe 'test attribute "currency"' do
|
|
47
|
+
it 'should work' do
|
|
48
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
49
|
+
end
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
end
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
=begin
|
|
2
|
+
#Zernio API
|
|
3
|
+
|
|
4
|
+
#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api
|
|
5
|
+
|
|
6
|
+
The version of the OpenAPI document: 1.0.4
|
|
7
|
+
Contact: support@zernio.com
|
|
8
|
+
Generated by: https://openapi-generator.tech
|
|
9
|
+
Generator version: 7.19.0
|
|
10
|
+
|
|
11
|
+
=end
|
|
12
|
+
|
|
13
|
+
require 'spec_helper'
|
|
14
|
+
require 'json'
|
|
15
|
+
require 'date'
|
|
16
|
+
|
|
17
|
+
# Unit tests for Zernio::FacebookPostEarningsResponse
|
|
18
|
+
# Automatically generated by openapi-generator (https://openapi-generator.tech)
|
|
19
|
+
# Please update as you see appropriate
|
|
20
|
+
describe Zernio::FacebookPostEarningsResponse do
|
|
21
|
+
#let(:instance) { Zernio::FacebookPostEarningsResponse.new }
|
|
22
|
+
|
|
23
|
+
describe 'test an instance of FacebookPostEarningsResponse' do
|
|
24
|
+
it 'should create an instance of FacebookPostEarningsResponse' do
|
|
25
|
+
# uncomment below to test the instance creation
|
|
26
|
+
#expect(instance).to be_instance_of(Zernio::FacebookPostEarningsResponse)
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
describe 'test attribute "success"' do
|
|
31
|
+
it 'should work' do
|
|
32
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
describe 'test attribute "account_id"' do
|
|
37
|
+
it 'should work' do
|
|
38
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
describe 'test attribute "post_id"' do
|
|
43
|
+
it 'should work' do
|
|
44
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
describe 'test attribute "platform"' do
|
|
49
|
+
it 'should work' do
|
|
50
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
describe 'test attribute "period"' do
|
|
55
|
+
it 'should work' do
|
|
56
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
57
|
+
# validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["lifetime"])
|
|
58
|
+
# validator.allowable_values.each do |value|
|
|
59
|
+
# expect { instance.period = value }.not_to raise_error
|
|
60
|
+
# end
|
|
61
|
+
end
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
describe 'test attribute "metrics"' do
|
|
65
|
+
it 'should work' do
|
|
66
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
67
|
+
end
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
describe 'test attribute "unavailable_metrics"' do
|
|
71
|
+
it 'should work' do
|
|
72
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
describe 'test attribute "data_delay"' do
|
|
77
|
+
it 'should work' do
|
|
78
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
79
|
+
end
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
end
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
=begin
|
|
2
|
+
#Zernio API
|
|
3
|
+
|
|
4
|
+
#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api
|
|
5
|
+
|
|
6
|
+
The version of the OpenAPI document: 1.0.4
|
|
7
|
+
Contact: support@zernio.com
|
|
8
|
+
Generated by: https://openapi-generator.tech
|
|
9
|
+
Generator version: 7.19.0
|
|
10
|
+
|
|
11
|
+
=end
|
|
12
|
+
|
|
13
|
+
require 'spec_helper'
|
|
14
|
+
require 'json'
|
|
15
|
+
require 'date'
|
|
16
|
+
|
|
17
|
+
# Unit tests for Zernio::FacebookPostEarningsResponseUnavailableMetricsInner
|
|
18
|
+
# Automatically generated by openapi-generator (https://openapi-generator.tech)
|
|
19
|
+
# Please update as you see appropriate
|
|
20
|
+
describe Zernio::FacebookPostEarningsResponseUnavailableMetricsInner do
|
|
21
|
+
#let(:instance) { Zernio::FacebookPostEarningsResponseUnavailableMetricsInner.new }
|
|
22
|
+
|
|
23
|
+
describe 'test an instance of FacebookPostEarningsResponseUnavailableMetricsInner' do
|
|
24
|
+
it 'should create an instance of FacebookPostEarningsResponseUnavailableMetricsInner' do
|
|
25
|
+
# uncomment below to test the instance creation
|
|
26
|
+
#expect(instance).to be_instance_of(Zernio::FacebookPostEarningsResponseUnavailableMetricsInner)
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
describe 'test attribute "metric"' do
|
|
31
|
+
it 'should work' do
|
|
32
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
describe 'test attribute "reason"' do
|
|
37
|
+
it 'should work' do
|
|
38
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
39
|
+
# validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error"])
|
|
40
|
+
# validator.allowable_values.each do |value|
|
|
41
|
+
# expect { instance.reason = value }.not_to raise_error
|
|
42
|
+
# end
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
describe 'test attribute "message"' do
|
|
47
|
+
it 'should work' do
|
|
48
|
+
# assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
|
|
49
|
+
end
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
end
|