Get campaign performance data

This guide shows you how to use the Campaigns API to retrieve campaign details and KPIs across all channels. Campaigns in Dash Social unify owned, earned, and creator content into a single cross-channel view for holistic measurement.

Use case examples

Campaign ROI Reporting

Pull topline KPIs for a product launch campaign to measure total reach, engagements, and video views across all channels.

UGC Impact Analysis

Fetch UGC content associated with a campaign to quantify earned media alongside owned posts.

Campaign Comparison

List all campaigns to compare topline metrics across multiple initiatives (e.g., Spring 2026 vs. Spring 2025).

Before you start

Make sure you have:

API access token with permissions to the relevant brand.
Brand ID for the account you want to query.

See API Quickstart for more details.

Implementation

Step 1: Retrieve all campaigns

Fetch the full list of campaigns for a brand. Use the returned id values to query individual campaigns in subsequent steps.

GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns

Key path parameters

brand_id: Your brand’s unique ID.

Sample Response:

{
    "data": [
        {
            "id": 4,
            "brand_id": 144,
            "name": "Ryan Test - Easter",
            "start_date": null,
            "end_date": null,
            "number_of_media": 118,
            "avg_engagement_rate": 0.254018,
            "total_engagements": 262,
            "total_impressions": 4154,
            "total_video_views": 2233,
            "total_clicks": 6,
            "included_media_sources": [
                "FACEBOOK",
                "INSTAGRAM",
                "INSTAGRAM_STORY",
                "PINTEREST",
                "TWITTER",
                "YOUTUBE"
            ],
            "included_creator_sources": [
                "INSTAGRAM",
                "YOUTUBE",
                "TIKTOK"
            ],
            "hashtags": [
                {
                    "hashtag_id": 3028,
                    "name": "france"
                }
            ],
            "created_at": "2026-04-13T11:46:52+00:00",
            "updated_at": "2026-03-18T19:56:44+00:00"
        }
    ]
}

Key response fields

Field	Description
`id`	Campaign ID — use this in subsequent API calls
`name`	Campaign name
`start_date` / `end_date`	Campaign date range (`null` if not set)
`number_of_media`	Total posts added to the campaign
`avg_engagement_rate`	Average engagement rate across all channels
`total_engagements`	Sum of all engagements across channels
`total_impressions`	Sum of all impressions across channels
`total_video_views`	Sum of all video views across channels
`total_clicks`	Sum of all link clicks across channels
`included_media_sources`	Owned channels included in this campaign
`included_creator_sources`	Creator channels included in this campaign
`hashtags`	Hashtags tracked in this campaign (for performance tracking only — does not auto-pull content)

Step 2: Retrieve a specific campaign

Fetch the full details for a single campaign by its ID.

GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}

Key path parameters

brand_id: Your brand’s unique ID.
campaign_id: The campaign ID from Step 1.

Sample Response:

{
    "id": 61237,
    "brand_id": 144,
    "name": "2026 Fall Season Launch",
    "start_date": "2026-09-01T00:00:00+00:00",
    "end_date": "2026-10-15T23:59:59+00:00",
    "number_of_media": 75,
    "avg_engagement_rate": 0.0858496,
    "avg_engagements": 2.33333,
    "total_engagements": 175,
    "total_impressions": 4682,
    "total_video_views": 836,
    "total_clicks": 3,
    "has_ugc": true,
    "included_media_sources": [
        "FACEBOOK",
        "INSTAGRAM",
        "PINTEREST",
        "TIKTOK",
        "TWITTER",
        "YOUTUBE"
    ],
    "included_creator_sources": [],
    "hashtags": [],
    "topline_metrics": {
        "OWNED_SUMMARY": [
            {
                "goal": null,
                "metric": "video_views_v2",
                "source": "campaign_stats"
            },
            {
                "goal": null,
                "metric": "engagements",
                "source": "campaign_stats"
            },
            {
                "goal": null,
                "metric": "avg_engagement_rate",
                "source": "campaign_stats"
            },
            {
                "goal": null,
                "metric": "impressions_v2",
                "source": "campaign_stats"
            },
            {
                "goal": null,
                "metric": "link_clicks",
                "source": "campaign_stats"
            }
        ]
    },
    "created_at": "2026-12-10T20:33:21+00:00",
    "updated_at": "2026-03-18T19:57:20+00:00"
}

Key response fields

Field	Description
`topline_metrics`	Configured summary metrics and optional goals for this campaign
`has_ugc`	Whether UGC content has been added to the campaign
`included_media_sources`	Owned channels contributing to campaign data

Step 3: Retrieve campaign media

Fetch owned posts associated with a campaign, filtered by channel and date range.

GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/media

Key query parameters

Parameter	Required	Description
`source`	Yes	Channel to filter by. Repeat the parameter to include multiple channels.
`source_created_on_or_after`	Yes	Start date filter (`YYYY-MM-DD`)
`source_created_on_or_before`	Yes	End date filter (`YYYY-MM-DD`)
`sort`	No	Sort order. Use `DATE` to sort by publish date (default).
`limit`	No	Number of results per page. Max `99`.
`offset`	No	Pagination offset.

Available `source` values

INSTAGRAM, PINTEREST, FACEBOOK, INSTAGRAM_STORY, TWITTER, TIKTOK, YOUTUBE, LIKESHOP, TIKTOK_LIKESHOP, RELATIONSHIPS, UGC, CREATORS_INSTAGRAM, CREATORS_INSTAGRAM_STORIES Example request for Facebook posts:

GET https://library-backend.dashsocial.com/brands/144/campaigns/61237/media?source=FACEBOOK&source_created_on_or_after=2026-01-01&source_created_on_or_before=2026-03-01&sort=DATE&limit=99&offset=0

Sample Response:

{
    "data": [
        {
            "id": 618008202,
            "brand_id": 144,
            "source": "FACEBOOK",
            "source_type": "OWNED",
            "type": "VIDEO",
            "source_id": "178420822757236_1985966815568805",
            "source_created_at": "2026-12-10T19:49:04",
            "collections": {
                "campaigns": [61237]
            },
            "facebook": {
                "message": "gif",
                "type": "video",
                "url": "https://www.facebook.com/1014506099381553/videos/878590275119927",
                "page_name": "Sunny Today",
                "organic_reach": 5,
                "organic_video_views": 3,
                "organic_engagements": 0,
                "organic_engagement_rate": 0.0,
                "organic_impressions": 0,
                "organic_link_clicks": 0,
                "paid_and_organic_reach": 5,
                "paid_and_organic_video_views": 3,
                "paid_and_organic_engagements": 0,
                "paid_and_organic_impressions": 0
            }
        }
    ],
    "paging": {
        "count": 1,
        "next": null,
        "previous": null
    }
}

Key response fields

Field	Description
`source`	The channel this post belongs to
`source_type`	`OWNED` for brand-posted content
`type`	Media type: `IMAGE`, `VIDEO`, `CAROUSEL`
`facebook` / `instagram` / `tiktok` / etc.	Platform-specific metrics object — only the relevant channel field is populated

Pagination: Use paging.next to detect additional pages, and increment offset by your limit value to retrieve them.

Step 4: Retrieve campaign UGC

Fetch user-generated content associated with a campaign.

GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/ugc

Key query parameters

Parameter	Required	Description
`type`	Yes	UGC type filter.
`source_created_on_or_after`	Yes	Start date filter (`YYYY-MM-DD`)
`source_created_on_or_before`	Yes	End date filter (`YYYY-MM-DD`)
`sort`	No	Sort order. Use `DATE` to sort by publish date.
`limit`	No	Number of results per page. Max `99`.
`offset`	No	Pagination offset.

Available `type` values

Value	Description
`MENTIONED`	Posts where your brand was @mentioned
`TAGGED`	Posts where your brand was photo-tagged
`ANY`	Either mentioned or tagged
`ALL`	All UGC regardless of mention/tag status

Example request:

GET https://library-backend.dashsocial.com/brands/144/campaigns/61237/ugc?type=MENTIONED&source_created_on_or_after=2026-01-01&source_created_on_or_before=2026-03-01&sort=DATE&limit=99&offset=0

Sample Response:

{
    "data": [
        {
            "id": 617880518,
            "brand_id": 144,
            "source": "INSTAGRAM",
            "source_type": "UGC",
            "type": "IMAGE",
            "source_created_at": "2026-12-10T15:02:56",
            "collections": {
                "campaigns": [61237]
            },
            "instagram": {
                "caption": "for u @sunny.today",
                "url": "https://www.instagram.com/p/DSFlan1APDu/",
                "is_mentioned": true,
                "is_tagged": false,
                "like_count": 2,
                "comments_count": 0,
                "engagements_public": 2,
                "engagement_rate_public": 0.2222222222222222,
                "reach": 1,
                "emv": 302.43
            },
            "instagram_user": {
                "handle": "_flapjackie",
                "followers": 8,
                "is_business": 1
            }
        }
    ],
    "paging": {
        "count": 1,
        "next": null,
        "previous": null
    }
}

Key response fields

Field	Description
`source_type`	Always `UGC` for this endpoint
`instagram.is_mentioned` / `is_tagged`	How this post relates to your brand
`instagram.emv`	Estimated Media Value for this UGC post
`instagram_user`	Creator profile info (handle, followers)

Step 5: Retrieve campaign statistics

Fetch aggregated daily statistics broken down by channel for a campaign. This powers the time-series charts in the Campaign Summary.

GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/stats

Key path parameters

brand_id: Your brand’s unique ID.
campaign_id: The campaign ID from Step 1.

Sample Response:

{
    "data": {
        "2026-11-28": {
            "FACEBOOK": {
                "number_of_media": 1.0,
                "number_of_videos": 1.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 5.0,
                "engagements": 1.0,
                "impressions": 0.0,
                "total_video_views": 4.0,
                "video_views": 4.0,
                "views": 16.0,
                "link_clicks": 0.0
            },
            "INSTAGRAM": {
                "number_of_media": 0.0
            },
            "INSTAGRAM_STORY": {
                "number_of_media": 0.0
            },
            "PINTEREST": {
                "number_of_media": 0.0
            },
            "TIKTOK": {
                "number_of_media": 0.0
            },
            "TWITTER": {
                "number_of_media": 0.0
            },
            "UGC": {
                "number_of_media": 0.0
            },
            "YOUTUBE": {
                "number_of_media": 0.0
            }
        },
        "2026-12-05": {
            "FACEBOOK": {
                "number_of_media": 2.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 4.0,
                "engagements": 1.0,
                "impressions": 0.0,
                "link_clicks": 0.0,
                "views": 12.0
            },
            "INSTAGRAM": {
                "number_of_media": 1.0,
                "number_of_videos": 1.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 1.0,
                "engagements": 0.0,
                "impressions": 0.0,
                "video_views": 0.0,
                "views": 5.0
            },
            "TIKTOK": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 2.0,
                "avg_retention_rate": 0.340816,
                "engagements": 0.0,
                "fyp_views_percentage": 0.333,
                "video_views": 3.0
            },
            "INSTAGRAM_STORY": {
                "number_of_media": 0.0
            },
            "PINTEREST": {
                "number_of_media": 0.0
            },
            "TWITTER": {
                "number_of_media": 0.0
            },
            "UGC": {
                "number_of_media": 0.0
            },
            "YOUTUBE": {
                "number_of_media": 0.0
            }
        },
        "2026-12-09": {
            "FACEBOOK": {
                "number_of_media": 1.0,
                "number_of_videos": 1.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 4.0,
                "engagements": 0.0,
                "impressions": 0.0,
                "total_video_views": 1.0,
                "video_views": 1.0,
                "views": 1.0
            },
            "INSTAGRAM": {
                "number_of_media": 4.0,
                "avg_engagement_rate": 0.014880975,
                "avg_reach": 7.25,
                "engagements": 5.0,
                "impressions": 0.0,
                "views": 129.0
            },
            "TIKTOK": {
                "number_of_media": 3.0,
                "avg_engagement_rate": 0.013333333333333334,
                "avg_reach": 83.33333333333333,
                "avg_retention_rate": 0.10478543333333333,
                "engagements": 5.0,
                "fyp_views_percentage": 0.9743333333333334,
                "video_views": 274.0
            },
            "TWITTER": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 0.0,
                "engagements": 0.0,
                "impressions": 2.0
            },
            "UGC": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 0.0,
                "engagements": 0.0,
                "estimated_reach": 7.0,
                "mentions": 0.0,
                "people_tags": 1.0
            },
            "INSTAGRAM_STORY": {
                "number_of_media": 0.0
            },
            "PINTEREST": {
                "number_of_media": 0.0
            },
            "YOUTUBE": {
                "number_of_media": 0.0
            }
        },
        "2026-12-10": {
            "FACEBOOK": {
                "number_of_media": 2.0,
                "number_of_videos": 2.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 4.0,
                "engagements": 0.0,
                "impressions": 0.0,
                "total_video_views": 4.0,
                "video_views": 4.0,
                "views": 22.0,
                "link_clicks": 0.0
            },
            "INSTAGRAM": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 0.222222,
                "avg_reach": 1.0,
                "engagements": 2.0,
                "impressions": 0.0,
                "views": 8.0
            },
            "PINTEREST": {
                "number_of_media": 19.0,
                "number_of_videos": 2.0,
                "avg_engagement_rate": 0.0045715863157894734,
                "engagements": 128.0,
                "impressions": 3800.0,
                "link_clicks": 0.0,
                "saves": 11.0,
                "video_views": 304.0
            },
            "TIKTOK": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 0.0,
                "avg_reach": 2.0,
                "avg_retention_rate": 0.05,
                "engagements": 0.0,
                "fyp_views_percentage": 0.0,
                "video_views": 4.0
            },
            "TWITTER": {
                "number_of_media": 1.0,
                "avg_engagement_rate": 1.0,
                "engagements": 3.0,
                "impressions": 3.0
            },
            "UGC": {
                "number_of_media": 2.0,
                "avg_engagement_rate": 0.444444,
                "engagements": 8.0,
                "estimated_reach": 92.0,
                "mentions": 1.0,
                "people_tags": 1.0
            },
            "YOUTUBE": {
                "number_of_media": 2.0,
                "avg_view_duration": 0.0,
                "engagements": 0.0,
                "likes": 0.0,
                "video_views": 0.0,
                "watch_time": 0.0
            },
            "INSTAGRAM_STORY": {
                "number_of_media": 0.0
            }
        }
    }
}

Response structure

The response is a dictionary keyed by date (YYYY-MM-DD). Each date contains a breakdown by channel. Only dates on which posts were published are returned — dates with no activity are omitted.

Key metrics by channel

Channel	Key Metrics
`INSTAGRAM`	`engagements`, `avg_engagement_rate`, `impressions`, `views`, `video_views`
`FACEBOOK`	`engagements`, `avg_engagement_rate`, `avg_reach`, `video_views`, `views`, `link_clicks`
`TIKTOK`	`video_views`, `engagements`, `avg_engagement_rate`, `avg_retention_rate`, `fyp_views_percentage`
`PINTEREST`	`engagements`, `impressions`, `saves`, `video_views`, `link_clicks`
`TWITTER`	`engagements`, `impressions`, `avg_engagement_rate`
`YOUTUBE`	`video_views`, `watch_time`, `engagements`, `avg_view_duration`
`UGC`	`engagements`, `avg_engagement_rate`, `estimated_reach`, `mentions`, `people_tags`
`INSTAGRAM_STORY`	`impressions`, `exits`, `link_clicks`, `avg_completion_rate`

Channels with number_of_media: 0 on a given date had no posts published that day. Metric fields for those channels will be null.

Documentation Index

​Use case examples

Campaign ROI Reporting

UGC Impact Analysis

Campaign Comparison

​Before you start

​Implementation

​Step 1: Retrieve all campaigns

​Key path parameters

​Key response fields

​Step 2: Retrieve a specific campaign

​Key path parameters

​Key response fields

​Step 3: Retrieve campaign media

​Key query parameters

​Available source values

​Key response fields

​Step 4: Retrieve campaign UGC

​Key query parameters

​Available type values

​Key response fields

​Step 5: Retrieve campaign statistics

​Key path parameters

​Response structure

​Key metrics by channel

Use case examples

Before you start

Implementation

Step 1: Retrieve all campaigns

Key path parameters

Key response fields

Step 2: Retrieve a specific campaign

Key path parameters

Key response fields

Step 3: Retrieve campaign media

Key query parameters

Available `source` values

Key response fields

Step 4: Retrieve campaign UGC

Key query parameters

Available `type` values

Key response fields

Step 5: Retrieve campaign statistics

Key path parameters

Response structure

Key metrics by channel