# Social Media Competitor Analytics API - Facelift Data Studio (`nabeelbaghoor/social-media-competitor-analytics-api`) Actor

Export social media analytics and competitor benchmarks from your own Facelift Data Studio (quintly) account: Facebook, Instagram, X, YouTube, LinkedIn and TikTok followers, posts and engagement over time via QQL, plus profile search and listing. Read only. Bring your own API keys.

- **URL**: https://apify.com/nabeelbaghoor/social-media-competitor-analytics-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Social media, Marketing, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 post or item returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Social Media Competitor Analytics API - Facelift Data Studio

Export social media analytics and competitor benchmarks from your own Facelift Data Studio (formerly quintly) account into a dataset, a spreadsheet or a warehouse: follower growth, posts and engagement for Facebook, Instagram, X (Twitter), YouTube, LinkedIn, TikTok, Threads, Pinterest, Snapchat and Google Business profiles, through the provider's SQL-like QQL. Uses your own API credentials, never changes anything in your account, and charges only for rows that carry data.

### What it collects

- **Time series metrics** for every profile in your account, your own and your competitors': Facebook Page likes, followers, people talking about, posts and reactions; Instagram followers and engagement; X followers, following and tweets; YouTube subscribers, views and videos; LinkedIn followers; and the private insights sources (reach, impressions, page views, video retention, audience by country, city, gender and age) for profiles whose owner has connected them. Daily, weekly, monthly or total for the period.
- **Posts and items** with their metrics: Facebook posts with each reaction type, comments, shares and interaction rate; Instagram posts and Reels; tweets and replies; YouTube videos with views, likes and comments; LinkedIn, TikTok, Threads and Pinterest posts; Facebook and Instagram comments; Google Business reviews and local posts; Meta ads and campaigns.
- **71 documented data sources and more than 2,300 documented columns**, picked from a dropdown, with your choice of columns checked against the provider's schema before anything is sent. A custom QQL query field covers joins and aggregates.
- **Filters**: date range, interval, time zone, profile IDs, post text keywords, post tags, ad accounts, and sorting on any column.
- **Profile search** across Facebook, X, YouTube, LinkedIn and Instagram by name, term, username or profile URL, to find competitor profiles to add in the web app.
- **Account lookups**: profiles (with the internal profile IDs the metrics mode uses), spaces, ad accounts and the data source catalogue.
- Read only, pay per result, bring your own credentials.

### How to use it

1. Get API access. The API is part of Facelift Data Studio business accounts; support issues a **client ID** and an **API secret** for your account.
2. Paste the client ID and the API secret into their fields (both are stored as secrets), or set the `DATA_API_AUTH_ID` and `DATA_API_KEY` secrets. You can also paste `clientId:secret` into the API secret field alone.
3. Run the default **Profiles** mode once to see your profiles and their IDs.
4. Switch to **Metrics and posts**, pick a data source (for example `facebook` for Page growth or `instagramOwnPosts` for posts), set the dates and interval, optionally list profile IDs, and run.

### Input

| Field | What it does |
| --- | --- |
| What to read | Profiles (default), metrics and posts, profile search, spaces, ad accounts or the data source catalogue. |
| Data source | One of the 71 documented QQL data sources, marked public or owner connection, time series or item level. |
| Columns | The columns to return. Empty means every documented column of the source. |
| Custom QQL query | A whole SELECT query; replaces the data source and columns. |
| Start date, End date | `YYYY-MM-DD`. Default: the last 30 days. |
| Interval | Daily, weekly, monthly or total. |
| Time zone | Default UTC. |
| Profile IDs | Internal profile IDs from the profiles mode. |
| Post text contains, Post tag IDs, Ad account IDs | The documented post text, post tag and ad account filters. |
| Sort by column, Sort direction | Any column of the source. Item level sources default to newest first. |
| Search term, Network | Profile search mode. |
| Space ID, Group ID | Profiles mode filters. |
| Maximum results | Row cap for the run. |
| Requests per minute | Pacing. |
| Client ID, API secret | Your credentials, as secret inputs or the `DATA_API_AUTH_ID` and `DATA_API_KEY` secrets. |

### Access, terms and limits on the provider side

- API keys are issued only for Facelift Data Studio business (enterprise) accounts, on request through support. There is no self-service sign-up for the API.
- **Usage terms.** The provider's terms and conditions grant a non-exclusive, non-transferable right of use, limited to the customer's own employees and governing bodies, and do not allow passing the usage on to third parties (including affiliated companies) unless agreed with the provider. Use this actor only with credentials for your own account, for your own organisation, and check your contract before sharing exported data or credentials with anyone else.
- Competitor and other public profiles must first be added to your account (in the web app); the metrics mode reads profiles already in the account. Data sources marked "owner connection" (insights, analytics, TikTok, Snapchat, Threads, Pinterest, Google Business) return rows only for profiles whose owner has granted private statistics access.
- The provider documents its rate limits as very loose. The actor still paces itself and waits out any rate limit answer.

### FAQ

#### What is a social media analytics API used for?

Getting the follower, post and engagement data a social media analytics platform collects into your own tools. A brand team loads daily follower growth of its own and five competitor Instagram profiles into a BI dashboard. An agency exports every Facebook and LinkedIn post of a client with reactions and shares for a monthly report. An analyst benchmarks YouTube subscriber growth across a market.

#### Which data source does this actor read?

The Facelift Data Studio API at api.quintly.com (version v0.9), the public API of Facelift Data Studio, formerly quintly, documented at api.quintly.com. It calls the qql, list-profiles, search-profiles, list-spaces, list-ad-accounts and list-data-sources routes. The documentation and the live host were checked on 2026-10-05.

#### Can I benchmark competitors?

Yes, once their public profiles are in your account. Use the profile search mode to find a competitor's Facebook, X, YouTube, LinkedIn or Instagram profile, add it in the web app, then read its public data sources (facebook, instagram, twitter, youtube, linkedIn and the matching posts sources) side by side with your own profiles.

#### What is QQL?

The provider's SQL-like query language over its data sources, for example `SELECT profileId, time, fans FROM facebook`. This actor builds the query for you from the data source and columns you pick, or runs your own query from the Metric Builder in the web app.

#### Why do I get no rows for an insights data source?

Sources marked owner connection hold private statistics, which exist only for profiles whose owner has connected them. Public sources work for every profile in the account.

#### Can this actor change anything in my account?

No. It only reads. The add profile, remove profile, private statistics activation and dashboard share link routes are not used. The credentials travel only in the Authorization header and are stripped from any error text.

#### How is it priced?

Pay per result: one price per post or item row, a lower price per time series row, and the lowest per profile, search result, space, ad account or data source row. Requests that find nothing are free. Your Facelift Data Studio subscription applies separately.

### Example output

A time series row from the `facebook` data source (weekly interval), shaped like the provider's documented answer:

```json
{
  "mode": "metrics",
  "modeLabel": "Metrics and posts (QQL)",
  "recordType": "metric",
  "dataSource": "facebook",
  "found": true,
  "id": 13,
  "profileId": 13,
  "name": null,
  "platformType": null,
  "time": "2013-12-30 00:00:00",
  "link": null,
  "fans": 1372,
  "retrievedAt": "2026-10-05T09:14:52.118Z",
  "note": null
}
```

A post row from `facebookOwnPosts` carries `uniqueId`, `profileId`, `time`, `message`, `type`, `link`, `likes`, `love`, `wow`, `haha`, `sad`, `angry`, `comments`, `shares`, `interactionRate` and the other selected columns. Profile rows carry `id`, `name`, `platformType`, `platformId`, `platformUsername`, `profileLink` and `isVerified`. Values are illustrative.

### Keyword map

social media analytics API, competitor benchmarking, social media competitor analysis, Facebook Page analytics, Instagram analytics export, X Twitter follower tracking, YouTube channel analytics, LinkedIn page analytics, TikTok analytics, social media reporting data, engagement rate, follower growth, quintly API, Facelift Data Studio API, QQL.

# Actor input Schema

## `mode` (type: `string`):

Profiles lists every profile in your account with the profile IDs the metrics mode filters on, and needs nothing else, so it is the default. Metrics and posts runs one QQL query over a data source for a date range. Profile search finds public profiles by name, term or URL. Spaces, ad accounts and the data source catalogue list the rest of the account.

## `dataSource` (type: `string`):

Metrics mode. The documented QQL data source (table) to read. Time series sources return one row per profile per interval (followers, fans, subscribers, engagement); item level sources return one row per post, video, comment or review. Public sources work for any profile in your account, competitors included; sources marked owner connection need the profile owner to connect private statistics.

## `columns` (type: `array`):

Metrics mode. The data source columns to return, exactly as the API documentation names them (for example profileId, time, fans, followersChange). Leave empty for every documented column of the data source.

## `qqlQuery` (type: `string`):

Metrics mode, advanced. A whole QQL SELECT query, for example one that joins the profiles table or uses an aggregate. When set it replaces the data source and columns above. Build and test queries in the Metric Builder of the web app.

## `startDate` (type: `string`):

Metrics mode. First day of the period, YYYY-MM-DD. Default: 30 days ago.

## `endDate` (type: `string`):

Metrics mode. Last day of the period, YYYY-MM-DD. Default: today.

## `interval` (type: `string`):

Metrics mode. Aggregation interval of time series sources. Weekly and monthly periods are expanded to whole weeks or months; total returns one row per profile.

## `timezone` (type: `string`):

Metrics mode. PHP time zone name used to fetch and aggregate, such as UTC or Europe/Berlin. Set explicitly so results do not depend on the account admin's setting.

## `profileIds` (type: `array`):

Metrics mode. Internal numeric profile IDs to read, as the profiles mode lists them. Leave empty for the provider default.

## `postTextKeywords` (type: `array`):

Metrics mode, item level sources. Keep only posts whose text contains any of these keywords.

## `postTagIds` (type: `array`):

Metrics mode, item level sources. Keep only posts carrying any of these post tag IDs (the postTags data source lists them).

## `adAccountIds` (type: `array`):

Metrics mode, ad data sources. Numeric ad account IDs, as the ad accounts mode lists them.

## `sortBy` (type: `string`):

Metrics mode. A column of the data source to sort on. Item level sources default to their creation time column, newest first.

## `sortDirection` (type: `string`):

Metrics mode.

## `searchQuery` (type: `string`):

Profile search. A profile name or term (Facebook, X, YouTube, LinkedIn), an Instagram username, or a profile URL such as https://www.facebook.com/quintly. TikTok and Snapchat profiles are not searchable; their owners must connect them.

## `network` (type: `string`):

Profile search. Limit results to one network. Leave empty for all searchable networks.

## `spaceId` (type: `string`):

Profiles mode. Only list profiles of this space (the spaces mode lists them).

## `groupId` (type: `string`):

Profiles mode. Only list profiles of this profile group.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for. QQL results are paged 1,000 rows at a time.

## `requestsPerMinute` (type: `integer`):

Pacing. The provider documents very loose rate limits; a rate limit answer is waited out and retried.

## `clientId` (type: `string`):

Your quintly client ID (Basic Auth user name), issued with the API secret by Facelift Data Studio support for business accounts. Stored as a secret. You can instead set the DATA_API_AUTH_ID environment secret.

## `apiKey` (type: `string`):

Your API secret (Basic Auth password). You can also paste clientId:secret here and leave the client ID empty. Stored as a secret. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "profiles",
  "dataSource": "facebook",
  "interval": "daily",
  "timezone": "UTC",
  "sortDirection": "desc",
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per metric row, post, profile, search result, space, ad account or data source.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/social-media-competitor-analytics-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/social-media-competitor-analytics-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nabeelbaghoor/social-media-competitor-analytics-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/social-media-competitor-analytics-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WYkugeWDOAqXpk4DA/builds/3OCfZhhnvNCYwtLHx/openapi.json