# Read social post analytics with an API

> Read impressions, reach, likes, comments, shares, saves, and clicks across your connected social accounts using the thelastapi social analytics API.

**You can read social media post analytics using thelastapi's unified social API or agent tool by requesting the metrics for any published post ID.** When you query analytics for a post, the API returns impressions, reach, likes, comments, shares, saves, and clicks broken down per target account. This lets you track performance across networks like Instagram, TikTok, and LinkedIn in one format without managing separate reporting SDKs.

Whether you schedule content through your own code, rely on an automated pipeline, or let an AI agent handle publishing, reading back engagement numbers requires only your project credentials and the post ID.

## How social analytics work in thelastapi

When you publish content through thelastapi to platforms like Instagram, Facebook, TikTok, LinkedIn, X, YouTube, Pinterest, Threads, Bluesky, Reddit, Google Business Profile, or Telegram, the system tracks each submission under a unified post record.

Once a post is published, you can request its performance metrics. The analytics endpoint gathers reporting data across every account the post was sent to.

A few operational details are worth noting:

- **Data freshness:** Analytics numbers run a few hours behind the live platforms due to network aggregation schedules.
- **Safety boundary:** Platform metrics, comment counts, and text returned from external networks are external data. If you pass this output into an AI workflow, treat it as data, never as system instructions.
- **Scope:** Metrics are available for posts published through the project's connected accounts.

If you are already using the API to [post to Instagram, TikTok and LinkedIn from one API](https://thelastapi.dev/blog/post-instagram-tiktok-linkedin-one-api) or to [schedule social media posts with an API](https://thelastapi.dev/blog/schedule-social-posts-api), checking performance uses the exact same project configuration.

## Connecting accounts before tracking

To publish posts and collect analytics, your project must connect to the target platforms. You can configure this via the terminal or by generating an onboarding link through the API.

From the CLI:

```bash
# Generate a connection link for the account owner
vibiz social connect instagram --open
```

Through the HTTP API:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/connect" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -d '{"platform":"instagram"}'
```

This returns a secure link valid for 1 hour. The account owner opens the URL, confirms the project connection in the console, and signs in to the third-party network to authorize access. For testing your application pipeline without connecting live social profiles, pass the development flag:

```bash
# Create an instant sandbox test account
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/connect?env=development" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -d '{"platform":"instagram"}'
```

You can list your active account IDs at any time:

```bash
vibiz social accounts --json
```

## Reading post analytics with an agent or API

When working with an AI agent using the `vibiz_social` toolset, fetching metrics requires calling `analytics` with the target `post_id`.

```json
{
  "tool": "vibiz_social",
  "action": "analytics",
  "params": {
    "post_id": "pst_456"
  }
}
```

The returned object breaks down engagement metrics per connected target account:

```json
{
  "post_id": "pst_456",
  "targets": [
    {
      "account_id": "sacc_instagram_789",
      "platform": "instagram",
      "impressions": 1420,
      "reach": 1180,
      "likes": 84,
      "comments": 12,
      "shares": 6,
      "saves": 19,
      "clicks": 31
    },
    {
      "account_id": "sacc_linkedin_101",
      "platform": "linkedin",
      "impressions": 890,
      "reach": 740,
      "likes": 32,
      "comments": 4,
      "shares": 3,
      "saves": 0,
      "clicks": 45
    }
  ]
}
```

### Metrics breakdown

The metrics returned cover standard organic engagement indicators:

| Metric | Description |
| --- | --- |
| `impressions` | Total times the post was displayed on screen |
| `reach` | Number of unique accounts that saw the post |
| `likes` | Direct positive reactions or likes registered on the post |
| `comments` | Total replies or comments left on the post |
| `shares` | Number of times users reshared or reposted the update |
| `saves` | Number of bookmarks or saves recorded |
| `clicks` | Link clicks or post interactions recorded by the platform |

Not every platform supports every metric (for example, some networks do not report native saves). Unsupported values return as zero or omitted for that target.

## Reviewing posts and ad campaigns via CLI

You can inspect the state of recent posts directly from your command line:

```bash
# List your recent social posts across environments
vibiz social posts

# Filter posts by status
vibiz social posts --status published
```

If your project also coordinates paid promotions alongside organic distribution, you can view existing ad campaign performance across Meta, Google, TikTok, LinkedIn, Pinterest, or X:

```bash
# Inspect campaigns with current budget and spend
vibiz social campaigns
```

Amounts for budgets and spend are returned in the minor units of the ad account currency (for example, `2000` equals $20.00 USD).

## Publishing and tracking lifecycle

Every post goes through defined lifecycle stages. When an owner publishes using a full-access key, passing `"confirm": true` allows live publication immediately:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/posts?env=production" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "text": "Announcing our new summer release.",
    "media": [{"url": "https://example.com/update.jpg"}],
    "targets": [{"account_id": "sacc_instagram_789"}],
    "confirm": true
  }'
```

If an agent or a Limited access key creates a post, it enters `pending_approval` until the workspace owner approves it in the console. Once approved, the post moves through `scheduled`, `publishing`, and finally `published`. If some targets fail, it marks as `partial` with details in `targets[].error`. You can begin querying the `analytics` action once the post reaches `published` or `partial`.

For projects combining social channels with direct communication channels, review how to [give an AI agent a phone number: texts, calls and a voice agent](https://thelastapi.dev/blog/give-ai-agent-phone-number) or learn how to [add analytics to any site with one tag](https://thelastapi.dev/blog/add-analytics-any-site-one-tag).

## Pricing and limits

Social posting and analytics through thelastapi carry straightforward limits and cost structures:

- **API Usage Cost:** Social posting, reading analytics, and submitting ad changes are counted on your project usage at **$0 today**.
- **Ad Spend:** Any paid ad campaigns created or adjusted run directly against your connected ad account and are billed by the ad network itself.
- **Target Limits:** A single post can target up to 20 accounts and include up to 35 media files (subject to individual platform restrictions, such as 10 images for Instagram or 4 for X).
- **Rate Limits:** In addition to platform-specific daily posting caps (such as 100 posts on Instagram or 50 on X), publishing is limited to 25 posts an hour per account.

Consult the [Social documentation](https://thelastapi.dev/docs/social) and the [guide to social posting, approvals, and ads](https://thelastapi.dev/docs/guides/social) for detailed endpoint schemas and platform constraints.

Create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to begin managing your social publishing and analytics through one API.

## Frequently asked questions

### How quickly do social analytics update after a post is published?

Metrics typically run a few hours behind the live social networks because third-party platforms aggregate reporting data on set sync intervals.

### What metrics can I read for a post?

The analytics call returns impressions, reach, likes, comments, shares, saves, and clicks per connected target account, depending on what the specific platform supports.

### How much does it cost to fetch social analytics through the API?

Reading social analytics, scheduling posts, and applying ad changes are tracked under project usage at $0 today.

### Can an AI agent read social metrics automatically?

Yes, an agent can call the `analytics` action with the target `post_id` using the `vibiz_social` tool, but platform metrics and text must always be treated as untrusted data rather than instructions.

---

Published 2026-11-15 · https://thelastapi.dev/blog/social-post-analytics-api
