# Instagram and TikTok profile and hashtag data with an API

> Fetch Instagram and TikTok profiles, follower counts, and hashtag posts using the thelastapi social actions with a single API call or CLI command.

**You can fetch Instagram and TikTok profile metrics and hashtag posts through one API call using the `social.profile` and `social.posts` actions.** thelastapi gives you a single API key to query creator handles, bios, follower counts, recent media, and hashtag feeds across both platforms without maintaining separate browser scripts or social integrations. Responses return structured JSON alongside execution duration and exact call cost.

Gathering creator statistics or monitoring hashtag campaigns usually requires building separate scrapers for each network, dealing with session logins, and adapting whenever site markup shifts. With [thelastapi web data actions](https://thelastapi.dev/docs/actions), social data is accessible via simple HTTP endpoints, the `vibiz` CLI, or application SDKs.

## What profile and hashtag data can you fetch?

Social data is split into two distinct actions: inspecting an individual creator account (`social.profile`) and collecting feeds based on topics or tags (`social.posts`). Both actions support Instagram and TikTok.

| Action | Platforms | Key inputs | What it returns |
| --- | --- | --- | --- |
| `social.profile` | `instagram`, `tiktok` | `handle`, `maxPosts?` (default 6, range 1–12) | Profile status (`public`, `private`, `not_found`), `displayName`, `bio`, `followers`, and recent `posts` |
| `social.posts` | `instagram`, `tiktok` | `hashtag` or `query`, `limit?` (default 20, range 1–50) | Post list: `url`, `caption`, `type`, `postedAt`, `likes`, `comments`, `views`, `author`, `thumbnail`, `hashtags` |

Every action runs synchronously. It accepts validated JSON inputs, inspects the target public pages, and returns clean structured fields.

## Fetching an Instagram or TikTok profile

When auditing creators or onboarding users, you often need to verify account existence, read bio text, check audience size, and retrieve recent posts.

The `social.profile` action takes three properties:
- `platform`: either `"instagram"` or `"tiktok"`
- `handle`: the creator's username without leading symbols
- `maxPosts` (optional): how many recent posts to include in the output (from 1 to 12, default 6)

### Calling from the CLI

Run `vibiz run` with your JSON input:

```bash
vibiz run social.profile --input '{"platform":"instagram","handle":"acme","maxPosts":6}'
```

To fetch a TikTok account, change the platform parameter:

```bash
vibiz run social.profile --input '{"platform":"tiktok","handle":"acme","maxPosts":10}'
```

### Calling over HTTP

Send a JSON payload to `POST /v1/actions/social.profile` with your bearer token:

```bash
curl https://thelastapi.dev/v1/actions/social.profile \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "platform": "instagram",
      "handle": "acme",
      "maxPosts": 6
    }
  }'
```

The response returns an `action_result` object containing the target account's details:

```json
{
  "object": "action_result",
  "action": "social.profile",
  "output": {
    "status": "public",
    "displayName": "Acme Brand",
    "bio": "Building tools for modern web applications.",
    "followers": 14250,
    "posts": [
      {
        "url": "https://www.instagram.com/p/C_abc123/",
        "caption": "Product release notes for our latest feature.",
        "type": "image",
        "postedAt": "2025-02-15T12:00:00Z",
        "likes": 320,
        "comments": 14,
        "thumbnail": "https://example.com/thumb1.jpg"
      }
    ]
  },
  "cost_micro_usd": 5000,
  "run_id": "arun_01j7abcde12345",
  "console_url": "https://thelastapi.dev/web-data?action=social.profile&run=arun_01j7abcde12345"
}
```

If the account exists but restricts visibility, `status` returns `"private"` with the bio and follower count, while `posts` remains empty. If the handle does not exist, `status` returns `"not_found"`.

### Calling from an application

Inside an application using `@vibiz/app`, run the action directly using the client:

```ts
import { vibiz } from '@vibiz/app';

const profile = await vibiz.actions.run('social.profile', {
  platform: 'tiktok',
  handle: 'acme',
  maxPosts: 5,
});

if (profile.output.status === 'public') {
  console.log(`${profile.output.displayName} has ${profile.output.followers} followers.`);
}
```

## Tracking hashtags and search terms across posts

When analyzing marketing campaigns, competitor mentions, or product launches, you need raw post data filtered by a specific hashtag or keyword. The `social.posts` action collects matching public content.

The action requires either a `hashtag` or a `query`, alongside the `platform` and an optional `limit` (default 20, up to 50):

```bash
vibiz run social.posts --input '{"platform":"tiktok","hashtag":"skincare","limit":25}'
```

Using HTTP:

```bash
curl https://thelastapi.dev/v1/actions/social.posts \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "platform": "instagram",
      "hashtag": "travelphotography",
      "limit": 20
    }
  }'
```

The output contains an array of posts matching your tag:

```json
{
  "object": "action_result",
  "action": "social.posts",
  "output": {
    "platform": "instagram",
    "posts": [
      {
        "url": "https://www.instagram.com/p/DA_xyz987/",
        "caption": "Sunset over the valley #travelphotography #mountains",
        "type": "video",
        "postedAt": "2025-02-20T18:42:00Z",
        "likes": 1280,
        "comments": 45,
        "views": 8500,
        "author": "mountain_trekker",
        "thumbnail": "https://example.com/thumb2.jpg",
        "hashtags": ["travelphotography", "mountains"]
      }
    ]
  },
  "cost_micro_usd": 5000,
  "run_id": "arun_01j7xyz98765",
  "console_url": "https://thelastapi.dev/web-data?action=social.posts&run=arun_01j7xyz98765"
}
```

Each post item breaks down engagement metrics (`likes`, `comments`, `views`), identifies the media `type`, parses all embedded `hashtags`, and names the posting `author`. If you generate content for your own campaigns after tracking what works, you can turn ideas into finished clips with [a vertical 9:16 video API for Shorts, Reels and TikTok](https://thelastapi.dev/blog/vertical-video-api-shorts-reels).

## Integrating social data into your broader stack

Extracting public profile and hashtag data is often just one step in market research or lead qualification workflows. Because all actions live on the same platform, you can combine social queries with other web data actions:

1. **Brand ad intelligence**: When checking an Instagram profile, query `ads.library` to see if that brand is running paid promotions across Facebook and Instagram. Use `vibiz ads "<brand>"` or `POST /v1/actions/ads.library`.
2. **B2B enrichment**: If you locate an executive or founder handle on Instagram, query their company footprint using [public LinkedIn company page data with an API](https://thelastapi.dev/blog/linkedin-company-page-data) via `linkedin.company`.
3. **Web verification**: Validate creator landing pages or storefronts with [scraping websites to markdown with one API call](https://thelastapi.dev/blog/scrape-website-to-markdown-api) using `web.scrape`.

Every action run is permanently recorded in your history. You can inspect past runs in the dashboard or via the CLI:

```bash
# List recent social action runs
vibiz runs --action social.profile

# Retrieve the full output of a specific past run
vibiz runs arun_01j7abcde12345
```

You can also list historical executions programmatically via `GET /v1/actions/runs?action=social.profile` or look up a run directly at `GET /v1/actions/runs/:id`.

## Timing, timeouts, and pricing

Because social actions load live web data, they take longer than standard database calls. Understanding their runtime characteristics helps you design reliable jobs.

### Execution times and timeouts

Actions like `social.profile` and `social.posts` typically complete in several seconds, but depending on platform responsiveness they can take a minute or two. Requests run up to a strict bound (60–150 seconds). If an external target stalls past that threshold, the action stops and returns HTTP `503`:

```json
{
  "error": {
    "code": "provider_unavailable",
    "details": {
      "reason": "timeout"
    }
  }
}
```

If you encounter timeouts when querying hashtag feeds, reduce the requested `limit` from 50 to 20 to speed up page parsing.

### Transparent costs

Every response contains `cost_micro_usd`, which represents the raw cost of running the action. Your account is billed that raw cost plus thelastapi's 30% margin on web data, drawn directly from your balance credits. Social queries generally run at roughly half a cent each.

All actions count toward your account's daily spend ceiling ($5 per day by default, shared with AI requests). If you hit your spend ceiling or balance limits, the API returns descriptive error codes:

- `400 invalid_request`: A missing or malformed field, such as supplying neither `hashtag` nor `query` to `social.posts`. The response includes `details.field` and `details.next_step`.
- `402 payment_required`: The account balance is depleted. Top up via `vibiz billing top-up`.
- `429 rate_limited`: The account reached its daily spend ceiling. Wait until midnight UTC or raise the limit in account settings.
- `503 provider_unavailable`: The action timed out or the external platform was temporarily unreachable.

You can inspect all available actions and their schemas at any time using `vibiz actions` or by querying `GET /v1/actions`.

Create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to get the API key and start automating social lookups.

## Frequently asked questions

### Can I fetch private Instagram or TikTok accounts using the API?

No. The `social.profile` action only extracts publicly visible information, returning a status of `"private"` with bio and follower metrics, but omitting private post details.

### What is the maximum number of posts returned for a hashtag search?

The `social.posts` action accepts a `limit` parameter between 1 and 50 posts per call, defaulting to 20.

### How do I choose between searching by hashtag or search query on social posts?

In `social.posts`, provide either the `hashtag` field (for exact hashtag indexing) or the `query` field (for general term search), but do not provide both in the same call.

### How are web data actions billed on thelastapi?

Each action reports its exact raw cost in `cost_micro_usd` on the response, and accounts are billed that amount plus a 30% margin drawn from balance credits.

---

Published 2026-11-15 · https://thelastapi.dev/blog/instagram-tiktok-profile-data-api
