> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Standalone analytics

> Track accounts and posts outside campaigns, organize them into collections, and query performance through /sdk/v1.

All endpoints below require:

* `X-Application-Id`
* `X-Api-Key`

Standalone analytics tracks social accounts and posts without adding them to a campaign. The API supports Instagram, TikTok, YouTube, Facebook, and X/Twitter URLs.

Paginated list endpoints accept `page` and `limit`, and return a top-level `pagination` object with `page`, `limit`, `total`, and `totalPages`.

## Track content

### POST /sdk/v1/analytics/tracked-media

Track one account or post. Grade detects the platform and target type from the URL and schedules the first scrape.

```json theme={null}
{
  "url": "https://www.tiktok.com/@creator/video/7350000000000000000",
  "trackStartAt": "2026-07-01T00:00:00.000Z",
  "collectionIds": ["collection_..."]
}
```

Optional fields:

* `platform`: `INSTAGRAM`, `TIKTOK`, `YOUTUBE`, `FACEBOOK`, or `TWITTER`
* `isAccount`: explicitly identify an ambiguous URL as an account or post
* `captionFilter`: account-only keyword, hashtag, mention, or phrase filter
* `trackRelativeValue` and `trackRelativeUnit`: how long discovered posts are tracked after upload; use `DAYS` or `MONTHS`
* `collectionIds`: collections to add the target to
* `forceScrape`: request a manual retry when an existing target is already being tracked; the retry is subject to the manual refresh policy below

The response includes the `trackedMediaId`, normalized URL, tracking configuration, scrape state, and whether the row was created, restored, or already existed. Reposting an existing or previously deleted target does not schedule another scrape unless `forceScrape` is true. Forced refreshes remain subject to the manual refresh policy below.

### POST /sdk/v1/analytics/tracked-media/bulk

Track up to 200 URLs in one request.

```json theme={null}
{
  "urls": [
    "https://www.instagram.com/creator/",
    "https://www.youtube.com/shorts/abc123xyz"
  ],
  "captionFilter": "#gradepartner",
  "collectionIds": ["collection_..."]
}
```

The response contains a result for each URL and a summary of created, existing, restored, duplicate, and failed items. Existing targets are not rescraped by the bulk endpoint.

## Manage tracked content

### GET /sdk/v1/analytics/tracked-media

List standalone tracked targets.

Query parameters:

* `type`: `accounts` or `posts`; omit to return both
* `page`: default `1`
* `limit`: default `20`, maximum `100`
* `q`: URL or normalized-target search

Account rows include metrics aggregated across discovered posts. Post rows include their latest views, likes, comments, and shares. Every row includes scrape state and issue information.

Tracked-media rows also expose normalized content metadata when the platform actor supplies it:

* Author: `authorPlatformId`, `authorUsername`, `authorDisplayName`
* Content: `title`, `captionText`, `hashtags`
* Audio: `audioPlatformId`, `audioTitle`, `audioArtist`, `audioAlbum`, `audioIsOriginal`
* Freshness: `metadataCollectedAt`

Unavailable actor fields are `null`; `hashtags` is an empty array when none are available. These fields are returned by the tracked-media list, detail, and discovered-post endpoints. They also appear on the nested `trackedMedia` object returned for collection members, on tracked video results from `/top`, and in `data.meta` from `/media/tracked/:trackedMediaId`.

### GET /sdk/v1/analytics/tracked-media/:trackedMediaId

Get one tracked account or post with its latest metrics and `asOfTimestamp`.

### GET /sdk/v1/analytics/tracked-media/:trackedMediaId/posts

List posts discovered from a tracked account.

Query parameters:

* `page`: default `1`
* `limit`: default `20`, maximum `100`

### PATCH /sdk/v1/analytics/tracked-media/:trackedMediaId/track-window

Update tracking configuration.

```json theme={null}
{
  "captionFilter": "#gradepartner",
  "trackRelativeValue": 30,
  "trackRelativeUnit": "DAYS"
}
```

You can also update `trackStartAt`. Send `trackRelativeValue: null` and `trackRelativeUnit: null` together to clear the relative window. `captionFilter` is only valid for accounts.

### POST /sdk/v1/analytics/tracked-media/:trackedMediaId/scrape-now

Request an immediate scrape. Scrape execution is asynchronous.

Manual refreshes use the same policy as campaign media: each tracked target can be refreshed up to three times, with a four-hour cooldown after each successfully queued refresh. A target in its cooldown returns `429` with `Retry-After`, `refreshAvailableAt`, and `refreshCooldownMs`. A target that has used all three refreshes returns `409` with code `ATM_REFRESH_LIMIT_REACHED`.

### PATCH /sdk/v1/analytics/tracked-media/:trackedMediaId/tracking-tier

Wake a sleeping target.

```json theme={null}
{
  "trackingTier": 1
}
```

Already-active targets return a successful no-op response.

### DELETE /sdk/v1/analytics/tracked-media/:trackedMediaId

Stop tracking a target. Deleting an account also soft-deletes its discovered child posts.

## Collections

### POST /sdk/v1/analytics/collections

Create a collection.

```json theme={null}
{
  "name": "Summer creators"
}
```

### GET /sdk/v1/analytics/collections

List collections with tracked-member counts and current views, likes, comments, and shares.

Query parameters:

* `page`: default `1`
* `limit`: default `20`, maximum `100`
* `q`: collection-name search

### PATCH /sdk/v1/analytics/collections/:collectionId

Rename a collection.

```json theme={null}
{
  "name": "Updated collection name"
}
```

### DELETE /sdk/v1/analytics/collections/:collectionId

Delete a collection and its member associations. This does not delete the tracked media itself.

Collections that also contain campaign members cannot be deleted through the standalone analytics API and return `409 Conflict`.

### GET /sdk/v1/analytics/collections/:collectionId/members

List standalone tracked accounts and posts in a collection.

Query parameters:

* `page`: default `1`
* `limit`: default `20`, maximum `100`
* `q`: target URL search

### POST /sdk/v1/analytics/collections/:collectionId/members

Add a tracked account or post to a collection.

```json theme={null}
{
  "trackedMediaId": "atm_..."
}
```

Adding an existing membership succeeds with `meta.duplicate: true`.

### DELETE /sdk/v1/analytics/collections/:collectionId/members/:memberId

Remove a tracked member from a collection without stopping its tracking.

## Query analytics

Analytics endpoints default to `scope=tracked`. They never include campaign media on the SDK surface.

Common query parameters:

* `startDate` and `endDate`: optional `YYYY-MM-DD` date range; defaults to the latest 30 days
* `platform`: `FACEBOOK`, `YOUTUBE`, `INSTAGRAM`, `TIKTOK`, or `TWITTER`
* `collectionIds`: comma-separated collection IDs
* `trackedMediaIds`: comma-separated tracked post IDs
* `trackedAccountIds`: comma-separated tracked account IDs; account IDs expand to their discovered posts
* `includeIncomplete`: include the current incomplete day

You can combine collection and tracked-ID filters. IDs are always scoped to the agency associated with the SDK application.

### GET /sdk/v1/analytics/summary

Return views, likes, comments, shares, bookmarks, engagements, engagement rate, virality, videos tracked, active accounts, and growth comparisons.

### GET /sdk/v1/analytics/series

Return daily values for one metric.

Additional parameters:

* `metric`: `views`, `likes`, `comments`, `shares`, `bookmarks`, `engagements`, `engagement_rate`, or `virality`
* `mode`: `delta` for change during each day or `total` for cumulative totals

### GET /sdk/v1/analytics/top

Rank tracked videos or accounts.

Tracked video results include the normalized author, content, hashtag, and audio fields described above. Tracked account results include available author identity fields and `metadataCollectedAt`.

Additional parameters:

* `type`: `videos` or `accounts`
* `metric`: supported analytics metric
* `mode`: `delta` or `total`
* `limit`: result count

### GET /sdk/v1/analytics/posting-activity

Return the number of posts published on each date, including account coverage metadata.

### GET /sdk/v1/analytics/posting-schedule

Group publishing performance by day of week and hour.

Additional parameters:

* `metric`: supported analytics metric
* `mode`: `delta` or `total`

### GET /sdk/v1/analytics/video-lengths

Group post performance by video-duration bucket.

Additional parameters:

* `metric`: supported analytics metric
* `mode`: `delta` or `total`
* `bucketPreset`: optional; defaults to `shortform_v1`

### GET /sdk/v1/analytics/media/tracked/:trackedMediaId

Return the date-range summary and daily series for one tracked post. `data.meta` includes the normalized author, content, hashtag, audio, and metadata-freshness fields described above.

Optional query parameters:

* `startDate` and `endDate`
* `metric`
* `mode`: `delta` or `total`

## Metric freshness

Analytics responses include `meta.asOfTimestamp`. This is the latest stored tracking snapshot used by the response and may be `null` before the first scrape completes.

Metric availability differs by platform. Responses include availability metadata when a metric is unsupported or only partially supported across the selected targets.