> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Campaigns > Endpoint to retrieve campaigns. Campaigns can be filtered by Vendor ID and status. It is expected to use for getting all campaigns of a marketplace & all campaigns of a vendor in dashboards. Filtering by status is expected to use at review page getting campaigns approved, pending tabs. ## OpenAPI ````yaml /openapi.json get /public/v1/campaign-service/campaigns openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /public/v1/campaign-service/campaigns: get: tags: - Campaign API summary: Get Campaigns description: >- Endpoint to retrieve campaigns. Campaigns can be filtered by Vendor ID and status. It is expected to use for getting all campaigns of a marketplace & all campaigns of a vendor in dashboards. Filtering by status is expected to use at review page getting campaigns approved, pending tabs. operationId: get_campaigns parameters: - name: vendor_id in: query required: false schema: description: The ID of the vendor. Omit to get campaigns for all vendors. oneOf: - type: string minLength: 1 - type: 'null' description: The ID of the vendor. Omit to get campaigns for all vendors. - name: status in: query required: false schema: description: Filter by the approval status of banner campaigns. oneOf: - $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' - type: 'null' description: Filter by the approval status of banner campaigns. - name: offset in: query required: false schema: type: integer minimum: 0 description: The pagination offset. default: 0 description: The pagination offset. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 0 description: The pagination limit. default: 100 description: The pagination limit. - name: is_active in: query required: false schema: description: >- Filter by active/inactive campaigns. When start_date or end_date is provided, this reflects the activation flag only, not whether the campaign is currently live. oneOf: - type: boolean - type: 'null' description: >- Filter by active/inactive campaigns. When start_date or end_date is provided, this reflects the activation flag only, not whether the campaign is currently live. - name: external_campaign_id in: query required: false schema: description: Filter by external campaign ID. oneOf: - type: string - type: 'null' description: Filter by external campaign ID. - name: slot_id in: query required: false schema: description: >- The ID of the slot. Used to filter banner and sponsored brand campaigns by slot. oneOf: - type: string - type: 'null' description: >- The ID of the slot. Used to filter banner and sponsored brand campaigns by slot. - name: ad_format in: query required: false schema: description: Filter by ad format. oneOf: - $ref: '#/components/schemas/Advanced_APIs_PublicAdFormat' - type: 'null' description: Filter by ad format. - name: sort_by_date in: query required: false schema: description: >- Optional sort by date of campaign creation. Deprecated. Use order_by instead. deprecated: true oneOf: - $ref: '#/components/schemas/Advanced_APIs_CampaignOrderByDirection' - type: 'null' description: >- Optional sort by date of campaign creation. Deprecated. Use order_by instead. deprecated: true - name: order_by in: query required: false schema: description: >- Comma-separated order by clauses, e.g. 'created_at:asc,name:desc'. Supported dimensions: created_at, start_date, end_date, name, campaign_id. oneOf: - type: string - type: 'null' description: >- Comma-separated order by clauses, e.g. 'created_at:asc,name:desc'. Supported dimensions: created_at, start_date, end_date, name, campaign_id. - name: start_date in: query required: false schema: description: >- Filter campaigns that are active on or after this date (campaigns whose end date is on or after this value). oneOf: - type: string format: date-time - type: 'null' description: >- Filter campaigns that are active on or after this date (campaigns whose end date is on or after this value). - name: end_date in: query required: false schema: description: >- Filter campaigns that are active on or before this date (campaigns whose start date is on or before this value). oneOf: - type: string format: date-time - type: 'null' description: >- Filter campaigns that are active on or before this date (campaigns whose start date is on or before this value). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_PublicCampaignsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_CampaignStatus: type: string enum: - approved - pending - rejected title: CampaignStatus description: Represents the review status of a banner campaign. Advanced_APIs_PublicAdFormat: type: string enum: - listing - banner title: PublicAdFormat description: Public campaign ad format filter options. Advanced_APIs_CampaignOrderByDirection: type: string enum: - asc - desc title: CampaignOrderByDirection description: The direction to order by. Advanced_APIs_PublicCampaignsResponse: properties: hasMore: type: boolean title: Hasmore description: Whether this is the last page of results or not. next: description: The parameters that should be used to fetch the next page. oneOf: - $ref: '#/components/schemas/Advanced_APIs_Next' - type: 'null' campaigns: items: $ref: '#/components/schemas/Advanced_APIs_PublicCampaign' type: array title: Campaigns description: An array of campaigns. type: object required: - hasMore - campaigns title: PublicCampaignsResponse description: The campaigns response. Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_Next: properties: offset: type: integer format: int32 title: Offset description: How many items to skip from the beginning of the list. limit: type: integer format: int32 title: Limit description: How many items to return. type: object required: - offset - limit title: Next Advanced_APIs_PublicCampaign: properties: campaignId: type: string format: uuid title: Campaignid description: The ID of the campaign. marketplaceId: type: string format: uuid title: Marketplaceid description: The ID of the marketplace. name: type: string minLength: 1 title: Name description: The name of the campaign. examples: - Bola-Bola Ad campaign budget: description: The budget assigned to the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_Budget' - type: 'null' startDate: type: string format: date-time title: Startdate description: The starting date of the campaign. endDate: type: string format: date-time title: Enddate description: The end date of the campaign. isActive: type: boolean title: Isactive description: Whether this campaign is active. isSmart: type: boolean title: Issmart description: Whether this campaign is "smart". campaignType: $ref: '#/components/schemas/Advanced_APIs_CampaignType' status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' statusUpdatedBy: title: Statusupdatedby description: >- The ID of the user who reviewed the campaign. If it's `null` and the status is not `"pending"` then it means this campaign has autoapproval status. oneOf: - type: string format: uuid - type: 'null' campaignBehaviorData: title: Campaignbehaviordata description: >- Deprecated. This field is always null. For behavioral data use reporting service. deprecated: true oneOf: - type: string - type: 'null' campaignBehaviorDataByDay: title: Campaignbehaviordatabyday description: >- Deprecated. This field is always null. For behavioral data use reporting service. deprecated: true oneOf: - type: string - type: 'null' createdAt: type: string format: date-time title: Createdat description: When was this campaign created. chargeType: title: Chargetype description: >- How campaigns are going to be charged, by click, by per mille impressions, or by action. oneOf: - $ref: '#/components/schemas/Advanced_APIs_ChargeType' - $ref: '#/components/schemas/Advanced_APIs_ExclusiveCampaignChargeType' exclusivityPrice: title: Exclusivityprice description: >- Daily price for an exclusive campaign, can only be set if a campaign is exclusive oneOf: - type: integer - type: 'null' targetRoas: title: Targetroas description: >- The target return on ad spend (ROAS) for this campaign. This is only applicable for autobidding listing campaigns. oneOf: - type: number - type: 'null' externalCampaignId: title: Externalcampaignid description: >- The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination. oneOf: - type: string - type: 'null' externalVendorId: type: string minLength: 1 title: Externalvendorid description: The ID of the vendor. Deprecated. Use vendor_id instead. deprecated: true adFormat: $ref: '#/components/schemas/Advanced_APIs_AdFormat' description: The ad format of the campaign. Can be listing or banner. examples: - listing isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. autobiddingObjective: description: The autobidding objective for the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_AutobiddingObjective' - type: 'null' vendorId: type: string minLength: 1 title: Vendorid description: The ID of the vendor. walletId: type: string format: uuid title: Walletid description: The uuid of the wallet to be used with this campaign. fallbackWalletId: title: Fallbackwalletid description: The optional fallback wallet to be used with this campaign. oneOf: - type: string format: uuid - type: 'null' bidCount: type: integer title: Bidcount description: >- The amount of active bids associated with this campaign. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true type: object required: - campaignId - marketplaceId - name - startDate - endDate - isActive - isSmart - campaignType - status - createdAt - chargeType - externalVendorId - adFormat - isAutoTrigger - vendorId - walletId - bidCount title: PublicCampaign description: The campaign model. Advanced_APIs_ValidationError: properties: loc: items: oneOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Advanced_APIs_Budget: properties: amount: type: integer exclusiveMaximum: 50000000000 exclusiveMinimum: 0 format: int64 title: Amount description: >- The amount of money in the budget in minor units of currency according to ISO 4217. examples: - 1000 amountRemaining: type: integer format: int64 title: Amountremaining description: >- The remaining amount of the budget. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true amountCarryover: type: integer format: int64 title: Amountcarryover description: >- The amount carried over from the last period. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true amountUsed: type: integer format: int64 title: Amountused description: >- The used amount of the budget. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true type: $ref: '#/components/schemas/Advanced_APIs_Type' examples: - daily type: object required: - amount - amountRemaining - amountCarryover - amountUsed - type title: Budget description: A campaign budget. Advanced_APIs_CampaignType: type: string enum: - manual - autobidding - exclusive title: CampaignType description: The bidding method for the campaign. Advanced_APIs_ChargeType: type: string enum: - CPM - CPC - CPA title: ChargeType description: >- Campaign charge type. CPM: cost per mille impressions CPC: cost per click CPA: cost per action. CPA reflects the total cost to achieve a conversion. Advanced_APIs_ExclusiveCampaignChargeType: type: string enum: - DAILY title: ExclusiveCampaignChargeType description: Charge types for exclusive campaigns. Advanced_APIs_AdFormat: type: string enum: - listing - banner - sponsored_brand - exclusive_listing - exclusive_banner - travel_listing - flight_listing title: AdFormat description: The type of the auction. Advanced_APIs_AutobiddingObjective: type: string enum: - impressions - clicks - conversions - revenue title: AutobiddingObjective Advanced_APIs_Type: type: string enum: - daily - weekly - monthly - total title: Type description: The periodicity of the budget. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key. scheme: bearer ````