Analytics API

GET /api/analytics/profile_username

Retrieves analytics data for a specified user profile across one or more social media platforms.

Method: GET

Endpoint URL: https://api.upload-post.com/api/analytics/profile_username

Description:

This endpoint provides key analytics metrics for a given social media profile associated with a user's account. It allows fetching data for multiple platforms in a single request. The system is designed to be extensible, with support for more platforms planned for the future.

Authentication:

A valid JSON Web Token (JWT) is required for authentication. The token must be included in the Authorization header as a Apikey token.

Authorization: Apikey <YOUR_JWT_TOKEN>

Parameters:

Parameter	Type	Location	Required	Description
`profile_username`	string	Path	Yes	The unique username of the profile for which you want to retrieve analytics.
`platforms`	string	Query	Yes	A comma-separated list of platforms to fetch analytics for. E.g., `?platforms=instagram,youtube,threads,pinterest,reddit`.
`page_id`	string	Query	No	Required for Facebook analytics. The ID of the Facebook Page.
`page_urn`	string	Query	No	Optional for LinkedIn. Defaults to "me" (personal profile). Use Organization URN/ID for pages.

Supported Platforms:

Currently, the following platforms are supported:

instagram
tiktok
Linkedin
Facebook
X (Twitter)
youtube
threads
pinterest
reddit
bluesky

Support for additional platforms will be added in the future. If you request a platform that is not yet supported, the response will include a message indicating this for that specific platform.

Here is an example of how to call the endpoint to get analytics for the test profile on Instagram, YouTube, Threads, Pinterest, and Reddit.

curl 'https://api.upload-post.com/api/analytics/test?platforms=instagram,youtube,threads,pinterest,reddit' \
--header 'Authorization: Apikey XXX...'

Example Successful Response (200 OK):

The response is a JSON object where each key corresponds to a requested platform. The value is another object containing the specific analytics data for that platform.

{
    "instagram": {
        "followers": 47,
        "impressions": 0,
        "profileViews": 0,
        "reach": 0,
        "reach_timeseries": [
            {
                "date": "2025-07-04",
                "value": 0
            },
            {
                "date": "2025-07-05",
                "value": 0
            },
            // ... more date entries
            {
                "date": "2025-08-02",
                "value": 0
            }
        ]
    }
}

Field Descriptions for Platform Analytics:

followers: Total number of followers.
impressions: Total number of times the profile's content was shown to users (views for YouTube/TikTok).
profileViews: Total number of times the profile was viewed (accounts engaged for Instagram).
reach: The number of unique accounts that have seen any of the profile's content.
likes: Total number of likes across the profile's content.
comments: Total number of comments across the profile's content.
shares: Total number of shares across the profile's content.
saves: Total number of saves across the profile's content.
reach_timeseries: An array of objects showing the daily reach or views value over the last 30 days. The dashboard filters this data client-side based on the selected date range.
metric_type: Indicates what the reach_timeseries represents for this platform. Values: "reach" (Facebook, Instagram, LinkedIn), "views" (YouTube, TikTok, Threads), "impressions" (X, Pinterest), "score" (Reddit). Use this to avoid double-counting when aggregating across platforms.
primary_impressions_field: The field name used as the primary metric for aggregation on this platform (e.g., "reach" for Instagram, "impressions" for YouTube).
available_metrics: Array of available metric keys for this platform.
metric_labels: Object mapping metric keys to user-friendly labels for this platform.

For a unified total impressions metric across platforms, see the Total Impressions section below.

Error Responses:

400 Bad Request: The platforms query parameter is missing or invalid.
401 Unauthorized: The JWT is missing, invalid, or expired.
404 Not Found: The specified profile_username does not exist for the authenticated user.
500 Internal Server Error: An unexpected error occurred on the server while fetching the data.

title: 'Total Impressions API'

GET /api/uploadposts/total-impressions/profile_username

Returns a unified "total impressions" metric for a profile, aggregated from daily analytics snapshots across all connected platforms.

Method: GET

Endpoint URL: https://api.upload-post.com/api/uploadposts/total-impressions/profile_username

Description:

This endpoint provides a single, deduplicated "total impressions" metric that intelligently combines reach and views data across platforms. Since different platforms report different types of impression metrics (Facebook and Instagram report "reach", YouTube and TikTok report "views"), this endpoint uses the most representative metric for each platform to avoid double-counting.

You can also request custom metrics aggregation by specifying which metrics to aggregate using the metrics parameter.

Authentication:

A valid JSON Web Token (JWT) is required. Include it in the Authorization header:

Authorization: Apikey <YOUR_JWT_TOKEN>

Parameters:

Parameter	Type	Location	Required	Description
`profile_username`	string	Path	Yes	The unique username of the profile.
`date`	string	Query	No	Single date in `YYYY-MM-DD` format. If provided, returns impressions for that day only.
`start_date`	string	Query	No	Start of date range in `YYYY-MM-DD` format. Defaults to 30 days ago.
`end_date`	string	Query	No	End of date range in `YYYY-MM-DD` format. Defaults to today.
`period`	string	Query	No	Shortcut for date range: `last_day`, `last_week`, `last_month`, `last_3months`, `last_year`. Overrides `start_date`/`end_date`.
`platform`	string	Query	No	Comma-separated list of platforms to filter by. E.g., `?platform=youtube,tiktok`.
`breakdown`	string	Query	No	Set to `true` to include per-platform and per-day breakdown in the response.
`metrics`	string	Query	No	Comma-separated list of metrics to aggregate. E.g., `?metrics=likes,comments,shares`. Available: `followers`, `reach`, `impressions`, `likes`, `comments`, `shares`, `saves`, `profileViews`, `video_count`, `following`. When provided, returns a `metrics` object instead of `total_impressions`.

Metric Selection per Platform (default mode):

Platform	Metric Used	Reason
Facebook	reach	Reports unique account reach
Instagram	reach	Reports unique account reach
LinkedIn	reach	Reports unique impressions
YouTube	impressions/views	Reports video view counts
TikTok	impressions/views	Reports video view counts
X	impressions	Reports tweet impression counts
Threads	impressions/views	Reports content view counts
Pinterest	impressions	Reports pin impression counts
Reddit	impressions/score	Reports post score as impressions proxy

Example Request:

curl 'https://api.upload-post.com/api/uploadposts/total-impressions/myprofile?start_date=2026-01-01&end_date=2026-01-31&breakdown=true' \
--header 'Authorization: Apikey XXX...'

Example Response (200 OK):

{
    "success": true,
    "profile_username": "myprofile",
    "start_date": "2026-01-01",
    "end_date": "2026-01-31",
    "total_impressions": 45230,
    "per_platform": {
        "instagram": 12500,
        "youtube": 18730,
        "tiktok": 8000,
        "facebook": 6000
    },
    "per_day": {
        "2026-01-01": 1200,
        "2026-01-02": 1450,
        "2026-01-03": 980
    }
}

Example with Period Shortcut:

curl 'https://api.upload-post.com/api/uploadposts/total-impressions/myprofile?period=last_week' \
--header 'Authorization: Apikey XXX...'

{
    "success": true,
    "profile_username": "myprofile",
    "start_date": "2026-02-13",
    "end_date": "2026-02-20",
    "total_impressions": 8523
}

Example with Custom Metrics:

curl 'https://api.upload-post.com/api/uploadposts/total-impressions/myprofile?period=last_month&metrics=likes,comments,shares&breakdown=true' \
--header 'Authorization: Apikey XXX...'

{
    "success": true,
    "profile_username": "myprofile",
    "start_date": "2026-01-21",
    "end_date": "2026-02-20",
    "metrics": {
        "likes": 4520,
        "comments": 312,
        "shares": 189
    },
    "per_platform": {
        "likes": { "instagram": 2100, "youtube": 1200, "tiktok": 1220 },
        "comments": { "instagram": 150, "youtube": 80, "tiktok": 82 },
        "shares": { "instagram": 90, "youtube": 45, "tiktok": 54 }
    },
    "per_day": {
        "likes": { "2026-01-21": 150, "2026-01-22": 160 },
        "comments": { "2026-01-21": 10, "2026-01-22": 12 },
        "shares": { "2026-01-21": 6, "2026-01-22": 8 }
    }
}

Example with Single Date:

curl 'https://api.upload-post.com/api/uploadposts/total-impressions/myprofile?date=2026-02-15' \
--header 'Authorization: Apikey XXX...'

{
    "success": true,
    "profile_username": "myprofile",
    "start_date": "2026-02-15",
    "end_date": "2026-02-15",
    "total_impressions": 1523
}

Example with Platform Filter:

curl 'https://api.upload-post.com/api/uploadposts/total-impressions/myprofile?platform=youtube,tiktok&breakdown=true' \
--header 'Authorization: Apikey XXX...'

{
    "success": true,
    "profile_username": "myprofile",
    "start_date": "2026-01-20",
    "end_date": "2026-02-19",
    "total_impressions": 26730,
    "platforms_filter": ["youtube", "tiktok"],
    "per_platform": {
        "youtube": 18730,
        "tiktok": 8000
    },
    "per_day": {
        "2026-01-20": 850,
        "2026-01-21": 920
    }
}

Error Responses:

400 Bad Request: Invalid date format (must be YYYY-MM-DD) or invalid metric name.
401 Unauthorized: The JWT is missing, invalid, or expired.
500 Internal Server Error: An unexpected error occurred on the server.

GET /api/uploadposts/post-analytics/request_id

Returns analytics for a specific post across all platforms it was published to.

Method: GET

Endpoint URL: https://api.upload-post.com/api/uploadposts/post-analytics/request_id

Description:

This endpoint provides per-post analytics by looking up the upload record and cross-referencing with stored analytics snapshots. It returns the post metadata along with platform-specific metrics at the time of posting and the latest available metrics.

Authentication:

A valid JSON Web Token (JWT) is required. Include it in the Authorization header:

Authorization: Apikey <YOUR_JWT_TOKEN>

Parameters:

Parameter	Type	Location	Required	Description
`request_id`	string	Path	Yes	The request ID of the upload.
`platform`	string	Query	No	Filter to a single platform (e.g., `?platform=x`). When provided, only metrics for that platform are fetched, which is significantly faster than fetching all platforms.

Example Request:

curl 'https://api.upload-post.com/api/uploadposts/post-analytics/abc123-def456' \
--header 'Authorization: Apikey XXX...'

Example Request (single platform):

curl 'https://api.upload-post.com/api/uploadposts/post-analytics/abc123-def456?platform=youtube' \
--header 'Authorization: Apikey XXX...'

Example Response (200 OK):

{
    "success": true,
    "post": {
        "request_id": "abc123-def456",
        "profile_username": "myprofile",
        "post_title": "My Video",
        "post_caption": "Check this out!",
        "media_type": "video",
        "upload_timestamp": "2026-02-10 14:30:00"
    },
    "platforms": {
        "youtube": {
            "success": true,
            "platform_post_id": "dQw4w9WgXcQ",
            "post_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
            "post_metrics": {
                "views": 5200,
                "likes": 120,
                "comments": 8,
                "favorites": 3
            },
            "post_metrics_source": "platform_api",
            "profile_snapshot_at_post_date": {
                "followers": 1500,
                "impressions": 45000,
                "likes": 320,
                "comments": 15,
                "shares": 8
            },
            "profile_snapshot_latest": {
                "followers": 1650,
                "impressions": 52000,
                "likes": 410,
                "comments": 22,
                "shares": 12
            },
            "profile_snapshot_latest_date": "2026-02-20"
        },
        "tiktok": {
            "success": true,
            "platform_post_id": "7123456789",
            "post_url": "https://tiktok.com/@user/video/7123456789",
            "post_metrics_error": "TikTok video not found (ID: 7123456789). The token may need to be refreshed.",
            "profile_snapshot_at_post_date": {
                "followers": 800,
                "impressions": 12000,
                "likes": 500,
                "comments": 30
            },
            "profile_snapshot_latest": {
                "followers": 950,
                "impressions": 18500,
                "likes": 780,
                "comments": 45
            },
            "profile_snapshot_latest_date": "2026-02-20"
        }
    }
}

Per-Platform Response Fields:

success: Whether the post was successfully published to this platform.
platform_post_id: The post's ID on the platform.
post_url: Direct URL to the published post.
post_metrics: Live metrics fetched from the platform's API for this specific post (views, likes, comments, shares, etc.).
post_metrics_source: Source of post metrics (currently "platform_api").
post_metrics_error: If post-level metrics could not be fetched, this field contains a human-readable error message explaining why.
profile_snapshot_at_post_date: Profile-level metrics snapshot from the day the post was published.
profile_snapshot_latest: Most recent profile-level metrics snapshot.
profile_snapshot_latest_date: Date of the latest snapshot.

Error Responses:

401 Unauthorized: The JWT is missing, invalid, or expired.
404 Not Found: No post found with the given request ID.
500 Internal Server Error: An unexpected error occurred on the server.

GET /api/uploadposts/platform-metrics

Returns the available metrics configuration for all supported platforms.

Method: GET

Endpoint URL: https://api.upload-post.com/api/uploadposts/platform-metrics

Description:

This public endpoint returns the metrics configuration for each social platform, including which metrics are available and which field is used as the primary "impressions" metric for aggregation.

Example Response (200 OK):

{
    "instagram": {
        "primary_impressions_field": "reach",
        "available_metrics": ["followers", "reach", "impressions", "profileViews", "likes", "comments", "shares", "saves"],
        "metric_labels": {
            "reach": "Unique Reach",
            "impressions": "Content Views",
            "profileViews": "Accounts Engaged"
        }
    },
    "youtube": {
        "primary_impressions_field": "impressions",
        "available_metrics": ["followers", "impressions", "likes", "comments", "shares"],
        "metric_labels": {
            "impressions": "Video Views",
            "followers": "Subscribers"
        }
    }
}

GET /api/analytics/profile_username​

title: 'Total Impressions API'​

GET /api/uploadposts/total-impressions/profile_username​

GET /api/uploadposts/post-analytics/request_id​

GET /api/uploadposts/platform-metrics​

GET /api/analytics/profile_username

title: 'Total Impressions API'

GET /api/uploadposts/total-impressions/profile_username

GET /api/uploadposts/post-analytics/request_id

GET /api/uploadposts/platform-metrics