GET
/
v1
/
teams
/
{teamId}
/
analytics
/
by-dimension
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.social.getAnalyticsByDimension({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  query: {
    "from": process.env.OCTOSPARK_FROM ?? "from",
    "to": process.env.OCTOSPARK_TO ?? "to",
    "groupBy": process.env.OCTOSPARK_GROUP_BY ?? "groupBy",
  },
})
[
  {
    "value": "<string>",
    "postCount": 123,
    "totals": {
      "likeCount": 123,
      "commentCount": 123,
      "shareCount": 123,
      "saveCount": 123,
      "impressionCount": 123,
      "reachCount": 123,
      "postCount": 123,
      "linkClickCount": 123,
      "averageEngagementRate": 123
    }
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Query Parameters

​
from
string
required

Start of the reporting window, ISO 8601 timestamp (inclusive).

Example:

"2026-05-01T00:00:00.000Z"

​
to
string
required

End of the reporting window, ISO 8601 timestamp (inclusive).

Example:

"2026-05-31T23:59:59.000Z"

​
platform
enum<string>

Restrict aggregates to one provider; omit for all connected providers.

Available options:
x,
tiktok,
instagram,
facebook,
youtube,
linkedin,
threads
Example:

"x"

​
postType
enum<string>

Restrict aggregates to one content format; empty or omitted includes all formats.

Available options:
text_post,
text_image,
text_video,
carousel,
thread,
​
tagIds
string

CSV of user-tag UUIDs; restricts aggregates to posts assigned ANY of these tags.

​
filter[postType]
enum<string>

Alias of postType using the filter[...] convention.

Available options:
text_post,
text_image,
text_video,
carousel,
thread,
​
filter[tagIds]
string

Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs.

​
filter[tags]
string

Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR).

Example:

"launch,product"

​
filter[category]
string

Comma-separated AI content categories; matches posts in any of the listed categories (OR).

Example:

"education"

​
filter[purpose]
string

Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR).

Example:

"promotion"

​
filter[emotion]
string

Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR).

Example:

"joy"

​
filter[mediaType]
string

Comma-separated media types; each value one of: image, video, audio, gif, document.

Example:

"image,video"

​
filter[enrichmentStatus]
string

Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed.

Example:

"completed"

​
groupBy
enum<string>
required

Content dimension to group post analytics by: platform, contentType, or userTag count a post once per bucket; asset-derived dimensions (mediaType, category, emotion, purpose) can count a post in multiple buckets.

Available options:
platform,
contentType,
userTag,
mediaType,
category,
emotion,
purpose
Example:

"platform"

Response

Success

​
dimension
enum<string>
required
Available options:
platform,
contentType,
userTag,
mediaType,
category,
emotion,
purpose
​
value
string
required
​
postCount
number
required
​
totals
object
required