# Competitor Analysis

Use the Competitor Analysis endpoints to list competitor accounts and fetch their high‑level analytics (followers, growth, engagement, reach, and posting mix). Combine with Post Insights and Best Times to build a full competitive benchmarking view.

### Requirements

**Authentication:** Bearer API token\
**Scope:** `analytics`          \
**Headers:**

* `Authorization: Bearer-API YOUR_API_KEY`
* `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### 1. List Competitors

Retrieve competitor accounts for the workspace or scoped to a specific social account.

```http
GET /api/v1/competitors/:account_id
```

#### Description

* Omit `:account_id` to list all competitors across the workspace.
* Provide `:account_id` to list competitors tied to a single social account.

#### URL Parameter

<table><thead><tr><th width="132.5650634765625">Parameter</th><th width="107.46759033203125">Type</th><th width="138.5596923828125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Social account ID to scope competitors.</td></tr></tbody></table>

## List Competitors

> Retrieves a list of competitor accounts for the workspace or for a specific social media account.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Competitors","description":"Endpoints for retrieving competitors and analytics"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/competitors/{account_id}":{"get":{"summary":"List Competitors","description":"Retrieves a list of competitor accounts for the workspace or for a specific social media account.","tags":["Competitors"],"parameters":[{"schema":{"type":"string"},"name":"account_id","in":"path","description":"ID of the social media account to retrieve competitors for.","required":false},{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve competitors from","required":true}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","description":"Social media provider (instagram, facebook, twitter, etc.)"},"name":{"type":"string","description":"Display name of the competitor account"},"social_id":{"type":"string","description":"Unique social media ID of the competitor"},"picture":{"type":"string","description":"Profile picture URL of the competitor"},"type":{"type":"string","description":"Type of account (user, page, etc.)"},"competitor_sync_in_queue":{"type":"boolean","description":"Whether competitor sync is currently queued"},"username":{"type":"string","description":"Username of the competitor (available for twitter, instagram, telegram, mastodon)"},"verified":{"type":"boolean","description":"Whether the account is verified (available for twitter, facebook)"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

Fields:

* `provider`: Social network (e.g., instagram, facebook, twitter).
* `name`: Display name of the competitor account.
* `social_id`: Network-unique ID.
* `picture`: Profile avatar URL.
* `type`: Account type (user, page, business, etc.).
* `competitor_sync_in_queue`: Whether a sync job is queued.
* `username`: Handle (available for twitter, instagram, facebook).
* `verified`: Whether the account is verified (available for twitter, facebook).

### 2. Get Competitors Analytics

Fetch paginated analytics for competitor accounts with filtering, sorting, and date range selection.

```
GET /api/v1/competitors/:account_id/analytics
```

#### Description

* Use `account_id` to focus on competitors relevant to a specific social account.
* Filter by `competitor_id` or search by name with `query`.
* Sort by followers, reach, engagement, and post mix counts.

#### URL Parameter

<table><thead><tr><th width="118.65557861328125">Parameter</th><th width="86.06414794921875">Type</th><th width="118.04095458984375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Scope analytics to one social account (path variant).</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="137.4339599609375">Parameter</th><th width="177.03118896484375">Type</th><th width="108.304931640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Scope analytics to one social account (query variant).</td></tr><tr><td><code>competitor_id</code></td><td>string</td><td>No</td><td>Analyze a specific competitor.</td></tr><tr><td><code>query</code></td><td>string</td><td>No</td><td>Case‑insensitive search by competitor name.</td></tr><tr><td><code>from</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>Start date (inclusive).</td></tr><tr><td><code>to</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>End date (inclusive).</td></tr><tr><td><code>page</code></td><td>integer</td><td>No</td><td>Page number (0‑based). Default <code>0</code>.</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>No</td><td>One of: <code>followers</code>, <code>reach</code>, <code>engagement</code>, <code>posts_count</code>, <code>videos_count</code>, <code>photos_count</code>, <code>links_count</code>, <code>statuses_count</code>. Default <code>followers</code>.</td></tr><tr><td><code>sort_type</code></td><td>string</td><td>No</td><td><code>asc</code> or <code>desc</code>. Default <code>asc</code>.</td></tr></tbody></table>

## Get Competitors Analytics

> Retrieves analytics data for competitor accounts, including engagement metrics, follower counts, and post performance statistics.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Competitors","description":"Endpoints for retrieving competitors and analytics"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/competitors/{account_id}/analytics":{"get":{"summary":"Get Competitors Analytics","description":"Retrieves analytics data for competitor accounts, including engagement metrics, follower counts, and post performance statistics.","tags":["Competitors"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve competitors analytics from","required":true},{"schema":{"type":"string"},"name":"account_id","in":"query","description":"ID of the social media account to filter competitors analytics for","required":false},{"schema":{"type":"string"},"name":"competitor_id","in":"query","description":"Specific competitor account ID to analyze","required":false},{"schema":{"type":"string"},"name":"query","in":"query","description":"Search filter for competitor account names","required":false},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)","required":false},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for analytics data (ISO 8601 format, e.g., 2023-12-31)","required":false},{"schema":{"type":"integer","minimum":0},"name":"page","in":"query","description":"Page number for pagination (default: 0)","required":false},{"schema":{"type":"string","enum":["followers","reach","engagement","posts_count","videos_count","photos_count","links_count","statuses_count"]},"name":"sort_by","in":"query","description":"Field to sort results by","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"name":"sort_type","in":"query","description":"Sort direction","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"insights":{"type":"array","description":"Array of competitor analytics data","items":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"string","description":"Competitor account ID"},"name":{"type":"string","description":"Competitor account name"},"provider":{"type":"string","description":"Social media provider"},"competitor_sync_in_queue":{"type":"boolean","description":"Whether sync is in progress"},"picture":{"type":"string","description":"Profile picture URL"},"my_account":{"type":"boolean","description":"Whether this is the user's own account"}}},"followers":{"type":"integer","description":"Current follower count"},"followers_growth":{"type":"integer","description":"Follower growth during the period"},"engagement":{"type":"integer","description":"Total engagement count"},"engagement_rate":{"type":"number","description":"Engagement rate percentage (for Twitter)"},"reach":{"type":"integer","description":"Total reach (not available for Instagram/Facebook)"},"posts_count":{"type":"integer","description":"Total number of posts"},"videos_count":{"type":"integer","description":"Number of video posts"},"photos_count":{"type":"integer","description":"Number of photo posts"},"links_count":{"type":"integer","description":"Number of link posts (not available for Instagram)"},"statuses_count":{"type":"integer","description":"Number of status posts (not available for Instagram)"}}}},"total":{"type":"integer","description":"Total number of competitor accounts"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied - requires analytics access or paying subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}},"422":{"description":"Unprocessable entity - service error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"string","description":"Error message from the service"}}}}}}}}}}}
```

Fields:

* `insights[]`: One item per competitor.
  * `account`: Basic account info and sync status; `my_account` indicates if it’s your own account.
  * `followers`: Current follower count.
  * `followers_growth`: Net growth in the selected period.
  * `engagement`: Total interactions (definition varies by network).
  * `engagement_rate`: Percentage (available for Twitter).
  * `reach`: Total reach (not available for Instagram/Facebook).
  * `posts_count`, `videos_count`, `photos_count`, `links_count`, `statuses_count`: Posting mix counts.
* `total`: Total competitors matching filters (use with `page` to paginate).

### Notes

* Reach availability: `reach` is not returned for Instagram/Facebook competitor analytics.
* **Best times for competitors**: Use [Best Times](https://publer.com/docs/analytics/best-times-to-post) endpoint with competitor mode to view competitors’ optimal posting hours:
  * GET /api/v1/analytics/:account\_id/best\_times?competitors=true\&competitor\_id=...
* **Competitor post insights**: Use the [Post Insights](https://publer.com/docs/analytics/post-insights) endpoint in competitor mode:
  * GET /api/v1/analytics/:account\_id/post\_insights?competitors=true\&competitor\_id=...

### Related Resources

* [Post Insights](https://publer.com/docs/analytics/post-insights) — Per‑post performance analytics (supports competitor mode)
* [Best Times ](https://publer.com/docs/analytics/best-times-to-post)— Suggested posting times (supports competitor mode)
* [Hashtag Analysis](https://publer.com/docs/analytics/hashtag-analysis) — Hashtag performance
* [Charts](https://publer.com/docs/analytics/charts) — Discover chart IDs and fetch chart data