---
title: "Track a competitor"
method: POST
path: "/pages/{id}/competitors"
tags: ["Competitors"]
---

# Track a competitor

`POST /pages/{id}/competitors`

Starts tracking a competitor for one of your pages, identified by @handle or profile URL. Capped at 5 competitors per page. Re-adding an already-tracked competitor is idempotent — it returns 200 with the existing row instead of creating a duplicate. Instagram, Facebook, YouTube, TikTok, LinkedIn pages only.

## Path parameters

- `id` string, required

## Request body

- object
  - `handle` string
  - `url` string

## Response `200`

Competitor was already tracked (idempotent re-add)

- object
  - `data` object, required
    - `trackedCompetitorId` string, required
    - `scrapedPageId` string, nullable, required
    - `handle` string, required
    - `displayName` string, required
    - `platform` string, required
    - `profileImageUrl` string, nullable, required
    - `syncStatus` string, required
    - `lastSyncedAt` string, date-time, nullable, required

## Other responses

- `201` — Competitor is now tracked
- `400` — Missing handle/url, unsupported page type, or the profile is currently unavailable
- `401` — Unauthorized
- `403` — Token lacks the write scope, the Analytics add-on is inactive, or the competitor cap is reached
- `404` — Page not found, or the handle could not be found on the platform
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/planable/apis/planable-public-api.md) · [All operations](https://skmtc.net/planable/apis/planable-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/planable/planable-public-api/revisions/e91a4f756dfe/schema)