Skip to content
AdVentur.aiAdVentur.aiAdVentur.ai Docs

Analytics API

Performance summaries, top posts and whole-account X analytics.

5 endpoints. Every path is relative to the API base URL and needs a bearer token unless it is marked public. See the REST API overview for authentication, errors and pagination.

GET/v1/orgs/{orgId}/marketing/analytics/performance

Bearer tokenMCP tool: get_performance_summary

Customer-facing performance analytics: published volume, impressions/engagement, top posts/topics, consistency and simple trends.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • daysinteger
  • topLimitinteger

Responses

200Customer-facing performance analytics: published volume, impressions/engagement, top posts/topics, consistency and simple trends.
  • dataobjectrequired
    Fields
    • windowDaysintegerrequired
    • generatedAtstringrequired
    • summaryobjectrequired
      Fields
      • postsPublishedintegerrequired
      • postsScheduledUpcomingintegerrequired
      • impressionsnumber | nullrequired
      • engagementsnumberrequired
      • engagementRatenumber | nullrequired
      • publishingActiveDaysintegerrequired
      • consistencyLabelstringrequired

        one of strong, steady, sparse, none

    • previousWindowobjectrequired
      Fields
      • postsPublishedintegerrequired
      • impressionsnumber | nullrequired
      • engagementsnumberrequired
    • trendsarray<object>required
      Item fields
      • datestringrequired
      • postsPublishedintegerrequired
      • impressionsnumber | nullrequired
      • engagementsnumberrequired
    • topPostsarray<object>required
      Item fields
      • postIdstring (uuid)required
      • platformstring | nullrequired

        one of x, linkedin, tiktok, reddit, facebook, instagram, youtube, bluesky, threads

      • publishedExternalIdstring | nullrequired
      • publishedUrlstring | nullrequired
      • contentTextstringrequired
      • publishedAtstring | nullrequired
      • likesnumberrequired
      • repostsnumberrequired
      • repliesnumberrequired
      • quotesnumberrequired
      • bookmarksnumber | nullrequired
      • impressionsnumber | nullrequired
      • engagementScorenumberrequired
      • topicstring | nullrequired
      • contentTypestring | nullrequired
    • topTopicsarray<object>required
      Item fields
      • topicstringrequired
      • postsPublishedintegerrequired
      • engagementsnumberrequired
      • impressionsnumber | nullrequired
    • topContentTypesarray<object>required
      Item fields
      • contentTypestringrequired
      • postsPublishedintegerrequired
      • engagementsnumberrequired
    • platformsarray<object>required
      Item fields
      • platformstringrequired

        one of x, linkedin, tiktok, reddit, facebook, instagram, youtube, bluesky, threads

      • postsPublishedintegerrequired
      • impressionsnumber | nullrequired
      • engagementsnumberrequired
    • audienceobjectrequired
      Fields
      • availablebooleanrequired
      • notestringrequired
      • accountsarray<object>required
        Item fields
        • socialAccountIdstringrequired
        • platformstringrequired

          one of x, linkedin, tiktok, reddit, facebook, instagram, youtube, bluesky, threads

        • namestring | nullrequired
        • followersinteger | nullrequired
        • changeinteger | nullrequired
        • trackingstringrequired

          one of live, pending, needs_permission

Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/analytics/performance" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

POST/v1/orgs/{orgId}/marketing/analytics/refresh

Bearer token

Path parameters

  • orgIdstring (uuid)required

Responses

200
  • dataobjectrequired
    Fields
    • processednumberrequired
    • updatednumberrequired
    • failednumberrequired
    • skippedFairUseinteger
    • errorsarray<object>
      Item fields
      • platformstringrequired
      • messagestringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/analytics/refresh" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

GET/v1/orgs/{orgId}/marketing/analytics/top-posts

Bearer tokenMCP tool: list_top_posts

The best-performing published posts over the last days (default 30), ranked by engagement. Returns { items, page, limit, total, hasMore }: limit is per page (default 10, max 50), page is 1-based; call again with page + 1 while hasMore is true.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • daysinteger
  • pageinteger
  • limitinteger

Responses

200
  • dataobjectrequired
    Fields
    • itemsarray<object>required
      Item fields
      • postIdstring (uuid)required
      • publishedExternalIdstring | nullrequired
      • publishedUrlstring | nullrequired
      • contentTextstringrequired
      • scheduledForUtcstring | nullrequired
      • likesnumberrequired
      • repostsnumberrequired
      • repliesnumberrequired
      • quotesnumberrequired
      • bookmarksnumber | nullrequired
      • impressionsnumber | nullrequired
      • engagementScorenumberrequired
      • fetchedAtstringrequired
    • pageintegerrequired
    • limitintegerrequired
    • totalintegerrequired
    • hasMorebooleanrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/analytics/top-posts" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

GET/v1/orgs/{orgId}/marketing/analytics/x-account

Bearer tokenMCP tool: get_x_account_analytics

Whole-account numbers for the connected X account, including posts made outside AdVentur.ai: impressions, engagements, profile visits, likes, reposts, replies, bookmarks, posts and replies per day, and followers.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • daysinteger

Responses

200Whole-account numbers for the connected X account, including posts made outside AdVentur.ai: impressions, engagements, profile visits, likes, reposts, replies, bookmarks, posts and replies per day, and followers.
  • dataobjectrequired
    Fields
    • enabledbooleanrequired
    • accountobject | nullrequired
      Fields
      • socialAccountIdstring (uuid)required
      • handlestring | nullrequired
      • namestring | nullrequired
    • lastSyncedAtstring | nullrequired
    • windowDaysintegerrequired
    • totalsobjectrequired
      Fields
      • impressionsintegerrequired
      • engagementsintegerrequired
      • engagementRatenumber | nullrequired
      • profileVisitsinteger | nullrequired
      • linkClicksinteger | nullrequired
      • likesintegerrequired
      • repostsintegerrequired
      • repliesintegerrequired
      • quotesintegerrequired
      • bookmarksintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
    • previousobject | nullrequired
      Fields
      • impressionsintegerrequired
      • engagementsintegerrequired
      • engagementRatenumber | nullrequired
      • profileVisitsinteger | nullrequired
      • linkClicksinteger | nullrequired
      • likesintegerrequired
      • repostsintegerrequired
      • repliesintegerrequired
      • quotesintegerrequired
      • bookmarksintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
    • audienceobjectrequired
      Fields
      • followersinteger | nullrequired
      • followerChangeinteger | nullrequired
      • followinginteger | nullrequired
      • postCountinteger | nullrequired
    • daysarray<object>required
      Item fields
      • datestringrequired
      • impressionsintegerrequired
      • engagementsintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
      • followerChangeinteger | nullrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/analytics/x-account" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

PUT/v1/orgs/{orgId}/marketing/analytics/x-account

Bearer token

Turns the daily read of the connected X account's own timeline on or off. Switching on reads the last 30 days straight away. Reads cost usage credits.

Path parameters

  • orgIdstring (uuid)required

Request body application/json

  • enabledbooleanrequired

Responses

200Turns the daily read of the connected X account's own timeline on or off. Switching on reads the last 30 days straight away. Reads cost usage credits.
  • dataobjectrequired
    Fields
    • enabledbooleanrequired
    • accountobject | nullrequired
      Fields
      • socialAccountIdstring (uuid)required
      • handlestring | nullrequired
      • namestring | nullrequired
    • lastSyncedAtstring | nullrequired
    • windowDaysintegerrequired
    • totalsobjectrequired
      Fields
      • impressionsintegerrequired
      • engagementsintegerrequired
      • engagementRatenumber | nullrequired
      • profileVisitsinteger | nullrequired
      • linkClicksinteger | nullrequired
      • likesintegerrequired
      • repostsintegerrequired
      • repliesintegerrequired
      • quotesintegerrequired
      • bookmarksintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
    • previousobject | nullrequired
      Fields
      • impressionsintegerrequired
      • engagementsintegerrequired
      • engagementRatenumber | nullrequired
      • profileVisitsinteger | nullrequired
      • linkClicksinteger | nullrequired
      • likesintegerrequired
      • repostsintegerrequired
      • repliesintegerrequired
      • quotesintegerrequired
      • bookmarksintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
    • audienceobjectrequired
      Fields
      • followersinteger | nullrequired
      • followerChangeinteger | nullrequired
      • followinginteger | nullrequired
      • postCountinteger | nullrequired
    • daysarray<object>required
      Item fields
      • datestringrequired
      • impressionsintegerrequired
      • engagementsintegerrequired
      • postsintegerrequired
      • repliesSentintegerrequired
      • followerChangeinteger | nullrequired
Request
curl -X PUT "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/analytics/x-account" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'