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.

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

Parameter	Type	Required	Description
account_id	string	No	Social account ID to scope competitors.

List Competitors

get

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

Authorizations

Bearer

Path parameters

account_idstringOptional

ID of the social media account to retrieve competitors for.

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve competitors from

Responses

200

Successful operation

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

/competitors/{account_id}

HTTPcURLJavaScriptPython

GET /api/v1/competitors/{account_id} HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*

[
  {
    "provider": "text",
    "name": "text",
    "social_id": "text",
    "picture": "text",
    "type": "text",
    "competitor_sync_in_queue": true,
    "username": "text",
    "verified": true
  }
]

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

Parameter	Type	Required	Description
account_id	string	No	Scope analytics to one social account (path variant).

Query Parameters

Parameter	Type	Required	Description
account_id	string	No	Scope analytics to one social account (query variant).
competitor_id	string	No	Analyze a specific competitor.
query	string	No	Case‑insensitive search by competitor name.
from	date (YYYY-MM-DD)	No	Start date (inclusive).
to	date (YYYY-MM-DD)	No	End date (inclusive).
page	integer	No	Page number (0‑based). Default 0.
sort_by	string	No	One of: followers, reach, engagement, posts_count, videos_count, photos_count, links_count, statuses_count. Default followers.
sort_type	string	No	asc or desc. Default asc.

Get Competitors Analytics

get

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

Authorizations

Bearer

Query parameters

account_idstringOptional

ID of the social media account to filter competitors analytics for

competitor_idstringOptional

Specific competitor account ID to analyze

querystringOptional

Search filter for competitor account names

fromstring · dateOptional

Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)

tostring · dateOptional

End date for analytics data (ISO 8601 format, e.g., 2023-12-31)

pageintegerOptional

Page number for pagination (default: 0)

sort_bystring · enumOptional

Field to sort results by

Possible values:

sort_typestring · enumOptional

Sort direction

Possible values:

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve competitors analytics from

Responses

200

Successful operation

application/json

401

Unauthorized

application/json

403

Permission denied - requires analytics access or paying subscription

application/json

422

Unprocessable entity - service error

application/json

get

/competitors/{account_id}/analytics

HTTPcURLJavaScriptPython

GET /api/v1/competitors/{account_id}/analytics HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*

{
  "insights": [
    {
      "account": {
        "id": "text",
        "name": "text",
        "provider": "text",
        "competitor_sync_in_queue": true,
        "picture": "text",
        "my_account": true
      },
      "followers": 1,
      "followers_growth": 1,
      "engagement": 1,
      "engagement_rate": 1,
      "reach": 1,
      "posts_count": 1,
      "videos_count": 1,
      "photos_count": 1,
      "links_count": 1,
      "statuses_count": 1
    }
  ],
  "total": 1
}

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 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 endpoint in competitor mode:

  • GET /api/v1/analytics/:account_id/post_insights?competitors=true&competitor_id=...

Related Resources

• Post Insights — Per‑post performance analytics (supports competitor mode)

• Best Times — Suggested posting times (supports competitor mode)

• Hashtag Analysis — Hashtag performance

• Charts — Discover chart IDs and fetch chart data