SocialClaw Analytics API
Read and refresh post, account, and run analytics.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/getsocialclaw-com:getsocialclaw-com-analytics-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: SocialClaw Analytics API
version: 1.0.0
description: Complete SocialClaw API reference for social account connections, media uploads, validation, scheduling, publishing, analytics, dashboard APIs, webhooks, and delivery URLs.
servers:
- url: https://getsocialclaw.com
description: SocialClaw production API
security:
- BearerAuth: []
tags:
- name: Analytics
description: Read and refresh post, account, and run analytics.
paths:
/v1/analytics/posts/{postId}:
get:
tags:
- Analytics
operationId: get_v1_analytics_posts_postId
summary: Post analytics
description: Returns the latest stored metrics snapshot for one published post. Native stats are available for Instagram, TikTok, YouTube, Reddit, X, Pinterest, and Snapchat; call POST /v1/analytics/refresh first to pull current numbers.
security:
- BearerAuth: []
parameters:
- name: postId
in: path
required: true
schema:
type: string
description: Post id.
- name: window
in: query
required: false
schema:
type: string
description: Metric window. Defaults to lifetime.
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, invalid, or unauthorized credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request body or semantic validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-socialclaw-auth: bearer
x-socialclaw-surface: public
/v1/analytics/accounts/{accountId}:
get:
tags:
- Analytics
operationId: get_v1_analytics_accounts_accountId
summary: Account analytics
description: Returns account-level metrics when provider support is available.
security:
- BearerAuth: []
parameters:
- name: accountId
in: path
required: true
schema:
type: string
description: Connected account id.
- name: window
in: query
required: false
schema:
type: string
description: Metric window. Defaults to lifetime.
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, invalid, or unauthorized credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request body or semantic validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-socialclaw-auth: bearer
x-socialclaw-surface: public
/v1/analytics/runs/{runId}:
get:
tags:
- Analytics
operationId: get_v1_analytics_runs_runId
summary: Run analytics
description: Returns aggregate metrics for a run.
security:
- BearerAuth: []
parameters:
- name: runId
in: path
required: true
schema:
type: string
description: Run id.
- name: window
in: query
required: false
schema:
type: string
description: Metric window. Defaults to lifetime.
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, invalid, or unauthorized credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request body or semantic validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-socialclaw-auth: bearer
x-socialclaw-surface: public
/v1/analytics/refresh:
post:
tags:
- Analytics
operationId: post_v1_analytics_refresh
summary: Refresh post analytics
description: Fetches fresh provider analytics for a published post and stores a snapshot. Native stats are supported for Instagram, TikTok, YouTube, Reddit, X, Pinterest, and Snapchat; other providers return an unsupported snapshot with the metric fields null.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsRefreshRequest'
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, invalid, or unauthorized credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request body or semantic validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-socialclaw-auth: bearer
x-socialclaw-surface: public
components:
schemas:
AnalyticsResponse:
type: object
description: Analytics response. `latest` is the most recent snapshot (post/account scope); `snapshot` is the one just written by a refresh. Each snapshot has `status` ("ready" when metrics were fetched, "unsupported" when the provider has no public post-metrics API or the post could not be resolved), `supported`, an optional `message`, and a `metrics` object with impressions, reach, views, likes, comments, shares, saves, and clicks (fields the provider does not return are null).
additionalProperties: true
properties:
ok:
const: true
latest:
type:
- object
- 'null'
additionalProperties: true
description: Most recent stored snapshot for this scope, or null.
snapshot:
type:
- object
- 'null'
additionalProperties: true
description: The snapshot written by a refresh call.
history:
type:
- array
- 'null'
items:
type: object
additionalProperties: true
description: Prior snapshots, newest first.
analytics:
type:
- object
- 'null'
additionalProperties: true
metrics:
type:
- object
- 'null'
additionalProperties: true
window:
type:
- string
- 'null'
description: Metric window.
required:
- ok
AnalyticsRefreshRequest:
type: object
description: Requests a fresh analytics fetch for a published post.
additionalProperties: false
properties:
postId:
type: string
description: Post id. Also accepted as post_id.
window:
type:
- string
- 'null'
description: Metric window, for example lifetime.
metricWindow:
type:
- string
- 'null'
description: Alias for window.
required:
- postId
ErrorResponse:
type: object
description: Standard error response returned by JSON API routes.
additionalProperties: false
properties:
ok:
const: false
description: Always false for errors.
code:
type:
- string
- 'null'
description: Stable machine-readable error code.
message:
type: string
description: Human-readable error message.
details:
type:
- object
- array
- string
- number
- boolean
- 'null'
description: Optional route-specific details.
required:
- ok
- message
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: SocialClaw API key
DashboardSession:
type: apiKey
in: cookie
name: socialclaw_dash_session
WebhookSignature:
type: apiKey
in: header
name: x-signature
externalDocs:
description: Human-readable SocialClaw API documentation.
url: https://getsocialclaw.com/docs/api
x-provenance:
method: harvested
publisher: SocialClaw
source: https://getsocialclaw.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)