API Reference
Analytics

Analytics

Real-time analytics endpoints that make a live call to the platform API (YouTube, Meta) and return the freshest available data for a single channel or a single post.

Use these when you need authoritative numbers — for example, to render a metrics widget the moment a user opens a channel page, or to fetch the live performance of a specific video. Each call counts against your platform-side API quota.

Base URL: https://pharlo.io
Auth: Authorization: Bearer ds_live_...

Both endpoints are billed as PLATFORM tier — every request triggers an outbound call to the underlying platform. For pricing details see Billing.

Endpoints

MethodPathDescriptionStatus
GET/api/v1/connections/{id}/channel-statsLive channel-level metrics200
GET/api/v1/connections/{id}/posts/{postId}/statsLive stats for a single post200

GET /api/v1/connections/{id}/channel-stats

Returns the current platform-level metrics for the channel behind a connection: subscribers, total views, total posts, and other counters that the platform exposes. The response reflects what the platform API returns at request time — no caching layer between you and the platform.

Example request

curl https://pharlo.io/api/v1/connections/7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b/channel-stats \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response 200 OK

{
  "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "platform": "youtube",
  "subscribers": 12400,
  "totalViews": 84320,
  "totalPosts": 142,
  "fetchedAt": "2026-05-18T12:00:00Z"
}
FieldTypeDescription
connectionIdUUIDConnection whose channel was queried
platformstringyoutube or facebook
subscribersintCurrent subscribers (YouTube) or followers (Meta)
totalViewsintLifetime view count, as reported by the platform
totalPostsintTotal published items on the channel/page
fetchedAtISO 8601When the platform was queried — useful for cache headers in your own app
⚠️

If the OAuth token for the connection is expired or missing, this endpoint returns 409 Conflict and you must refresh the token via POST /connections/{id}/refresh-token.

GET /api/v1/connections/{id}/posts/{postId}/stats

Returns live metrics for a single post (video, reel, etc.) published through Pharlo. postId is the id of an assignment whose status is published.

Example request

curl https://pharlo.io/api/v1/connections/7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b/posts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stats \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response 200 OK

{
  "postId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "platform": "youtube",
  "views": 18420,
  "likes": 1240,
  "comments": 87,
  "shares": 56,
  "fetchedAt": "2026-05-18T12:00:00Z"
}
FieldTypeDescription
postIdUUIDAssignment ID that produced this post
connectionIdUUIDChannel the post belongs to
viewsintCurrent view count from the platform
likesintLikes / reactions
commentsintComment count
sharesintShares / reposts (when supported by the platform)
fetchedAtISO 8601When the platform was queried

Error responses

StatusReason
400Invalid connectionId or postId format
401Missing or invalid API key
404Connection or post not found, or post is not in published state
409OAuth token expired or missing — refresh the connection token before retrying
429Platform-side rate limit hit — retry after the delay returned in Retry-After

For a full guide on handling errors and retries, see Error Handling.

See also

  • Connections — manage the channels these stats are queried for
  • Assignments — get the postId for a published assignment
  • Analytics guide — when to use live stats vs. consuming the platform API directly
ConnectionsPlatforms