--- title: "List Paid campaigns, ad sets, or ads" method: POST path: "/v1/analytics/paid/{adEntityCollection}" tags: ["Analytics"] --- # List Paid campaigns, ad sets, or ads `POST /v1/analytics/paid/{adEntityCollection}` ## Request - Base URL: `https://platform.hootsuite.com` - URL: `https://platform.hootsuite.com/v1/analytics/paid/{adEntityCollection}` - Auth: OAuth 2 - Authorization code: `https://platform.hootsuite.com/oauth2/auth` - Token URL: `https://platform.hootsuite.com/oauth2/token` Returns paid entities for the collection given in the path (`campaigns`, `adsets`, or `ads`). Use query parameters for ad account type, pagination, and datatype; use the request body for filters (ad accounts, time range, etc.) note: In this API, 'adsets' and related response fields map to Facebook ad sets and Twitter ad groups ('adgroups'). ## Path parameters - `adEntityCollection` 'campaigns' | 'adsets' | 'ads', required: Plural collection name used in the URL path. Determines whether the response contains campaigns, ad sets, or ads ## Query parameters - `datatype` 'ORGANIC' | 'PAID': API code for this datatype - `adAccountType` 'FACEBOOK' | 'TWITTER': Ad account network type - `cursor` string - `limit` integer ## Request body - ListPaidRequest - `filters` AdRequestFilters, required - `adAccounts` AdAccountFilter[], required - `adAccountId` string, required - `organizationId` string, required - `lastModified` TimeFieldFilters: Filter by a time field, at least one filter must be specified. - `timespan` TimespanFilter: Timespan to filter against, inclusive. At least one of `since` or `until` must be provided. - `since` string, date: Start of query, if omitted defaults to 1 year ago - `until` string, date: End of query, if omitted defaults to now - `reportingPeriod` TimeFieldFilters: Filter by a time field, at least one filter must be specified. - `timespan` TimespanFilter: Timespan to filter against, inclusive. At least one of `since` or `until` must be provided. - `since` string, date: Start of query, if omitted defaults to 1 year ago - `until` string, date: End of query, if omitted defaults to now ## Response `200` data successfully returned for the selected paid entity collection. - ListPaidResponse: Response payload for listing paid entities (campaigns, ad sets, or ads). - `data` union[], required - union - Campaign: Paid campaign entity returned from ad platform integrations. - `adAccountId` string, required: Internal identifier of the ad account. - `organizationId` string, required: Hootsuite orgnization Id. - `externalCampaignId` string, required: Campaign identifier from the external ad platform. - `campaignStatus` string, required: Current campaign status reported by the external ad platform. - `name` string, required: Campaign name. - `objective` string, required: Marketing objective configured for the campaign. - `adAccountType` 'FACEBOOK' | 'TWITTER', required: Ad account network type - `currency` string, required: Currency code used for campaign spending and budgets (for example, USD). - `externalAdAccountId` string, required: Account identifier from the external ad platform. - `createdAt` string, date-time: Timestamp when the campaign was created in the external platform. - `lastModifiedAt` string, date-time: Timestamp when the campaign was last updated in the external platform. - `hsCollectedAt` string, date-time: Timestamp when Hootsuite last collected this campaign record. - `budget` Budget: Budget configuration, when available. - `daily` number, double, required - `lifetime` number, double, required - `lifecycle` Lifecycle: Schedule window (start and end time), when available. - `startTime` string, date-time - `endTime` string, date-time - `marketingMetadata` AdMetadata, required: Platform-specific metadata in a single object. Keys and values depend on ad_account_type. - AdSet: Paid ad set entity returned from ad platform integrations. - `adAccountId` string, required: Internal identifier of the ad account. - `organizationId` string, required: Hootsuite orgnization Id. - `externalAdsetId` string, required: Ad set identifier from the external ad platform. - `adSetStatus` string, required: Current ad set status reported by the external ad platform. - `name` string, required: Ad group name. - `objective` string, required: Marketing objective associated with this ad set. - `adAccountType` 'FACEBOOK' | 'TWITTER', required: Ad account network type - `currency` string, required: Currency code used for spending and budget values (for example, USD). - `externalAdAccountId` string, required: Account identifier from the external ad platform. - `externalCampaignId` string, required: Parent campaign identifier from the external ad platform. - `campaignName` string, required: Name of the parent campaign. - `createdAt` string, date-time: Timestamp when the ad set was created in the external platform. - `lastModifiedAt` string, date-time: Timestamp when the ad set was last updated in the external platform. - `hsCollectedAt` string, date-time: Timestamp when Hootsuite last collected this ad set record. - `budget` Budget: Budget configuration, when available. - `daily` number, double, required - `lifetime` number, double, required - `lifecycle` Lifecycle: Schedule window (start and end time), when available. - `startTime` string, date-time - `endTime` string, date-time - `marketingMetadata` AdMetadata, required: Platform-specific metadata in a single object. Keys and values depend on ad_account_type. - Ad - `adAccountId` string, required: Internal identifier of the ad account. - `organizationId` string, required: Hootsuite orgnization Id. - `name` string, required: Ad name. - `objective` string, required: Marketing objective associated with this ad. - `adAccountType` 'FACEBOOK' | 'TWITTER', required: Ad account network type - `currency` string, required: Currency code used for spending and budget values (for example, USD). - `externalAdAccountId` string, required: Account identifier from the external ad platform. - `body` string, required: Primary ad text or message body. - `externalAdId` string, required: Ad identifier from the external ad platform. - `adType` string, required: Ad format/type reported by the external ad platform. - `adStatus` string, required: Current ad status reported by the external ad platform. - `adManagerUrl` string, required: URL to open/manage this ad in the external ad manager. - `campaignName` string, required: Name of the parent campaign. - `adsetName` string, required: Name of the parent ad set. - `targetUrl` string, required: Destination URL the ad points to. - `externalAdsetId` string, required: Ad set identifier from the external ad platform. - `externalCampaignId` string, required: Campaign identifier from the external ad platform. - `externalCreativeId` string, required: Creative identifier associated with this ad in the external platform. - `tags` string[], required: User-assigned marketing tags attached to the ad. - `autoTags` string[], required: Automatically generated tags attached to the ad. - `thumbnail` AdMedia: Thumbnail and media URLs for the ad, when available. - `thumbnailUrl` string, required - `url` string, required - `links` AdLink[] - `extendedUrl` string, required - `utm` UTM: UTM objects associated with the ad. - `campaign` string, required - `content` string, required - `medium` string, required - `source` string, required - `term` string, required - `attachedUrls` string[], required: Raw attached URLs associated with the ad content. - `createdAt` string, date-time: Timestamp when the ad was created in the external platform. - `lastModifiedAt` string, date-time: Timestamp when the ad was last updated in the external platform. - `hsCollectedAt` string, date-time: Timestamp when Hootsuite last collected this ad record. - `marketingMetadata` AdMetadata: Platform-specific metadata in a single object. Keys and values depend on ad_account_type. - `metadata` Metadata, required - `collectionInfo` CollectionInfo, required - `next` Cursor - `cursor` string, required: Cursor for the next/prev page of data, if available - `prev` Cursor - `cursor` string, required: Cursor for the next/prev page of data, if available ## Other responses - `default`: An error occurred. --- [API](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api.md) - [All operations](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/revisions/adac53bd28bb?raw)