> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Get campaign seller scorecard > Score each seller in a campaign on delivery, price, performance and quality, from the buyer's own media buys in it. Each dimension carries its value, the seller's rank on that dimension alone, and who counted it; there is no blended score. A dimension with no data is not reported and has no rank. Price is the buyer's gross cost, including the platform fee. Covers the campaign's whole reported life unless startDate or endDate narrow it. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /campaigns/{campaignId}/seller-scorecard openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.apostra.com/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.apostra.com/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /campaigns/{campaignId}/seller-scorecard: get: tags: - Campaigns summary: Get campaign seller scorecard description: >- Score each seller in a campaign on delivery, price, performance and quality, from the buyer's own media buys in it. Each dimension carries its value, the seller's rank on that dimension alone, and who counted it; there is no blended score. A dimension with no data is not reported and has no rank. Price is the buyer's gross cost, including the platform fee. Covers the campaign's whole reported life unless startDate or endDate narrow it. operationId: getCampaignSellerScorecard parameters: - in: query name: startDate schema: description: >- First day to score (YYYY-MM-DD). Defaults to the campaign's first reported day. example: '2026-09-01' type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- First day to score (YYYY-MM-DD). Defaults to the campaign's first reported day. - in: query name: endDate schema: description: Last day to score (YYYY-MM-DD). Defaults to today. example: '2026-09-30' type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Last day to score (YYYY-MM-DD). Defaults to today. - in: path name: id schema: type: string minLength: 1 description: Unique identifier for the campaign example: cmp_987654321 required: true description: Unique identifier for the campaign responses: '200': description: Get campaign seller scorecard content: application/json: schema: $ref: '#/components/schemas/CampaignSellerScorecardResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- FEATURE_NOT_ENABLED: the campaign seller scorecard is not enabled for this account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No live campaign with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: CampaignSellerScorecardResponse: type: object properties: campaignId: type: string periodStart: type: string description: First day scored. periodEnd: type: string description: Last day scored. currency: nullable: true description: The advertiser currency money is in. Null when nothing was reported. type: string priceUnit: type: string enum: - impressions - clicks - views - completedViews - conversions - leads - viewableImpressions description: >- The unit every seller's price is in: the primary goal's unit, or impressions. pricePerUnits: anyOf: - type: number enum: - 1 - type: number enum: - 1000 description: 1000 for impressions (a price per thousand), 1 otherwise. sellers: type: array items: $ref: '#/components/schemas/CampaignSellerScorecardRow' description: >- One row per seller with a live media buy in the campaign, or a buy that delivered in the period; most spend first. moneyCoverage: description: >- Whether the reporting store holds every day the period covers. When it is not complete, spend is understated, so every seller reads delivery and price as not reported. allOf: - $ref: '#/components/schemas/ReportingMoneyCoverage' unattributedMediaBuyIds: type: array items: type: string description: >- Media buys whose products span more than one Storefront, so they belong to no single seller and are not scored. required: - campaignId - periodStart - periodEnd - currency - priceUnit - pricePerUnits - sellers - moneyCoverage - unattributedMediaBuyIds additionalProperties: false description: >- Each seller in a campaign scored on delivery, price, performance and quality, from the buyer's own media buys. Four scores, never one: each dimension is ranked on its own. ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response CampaignSellerScorecardRow: type: object properties: storefrontId: type: string description: The Storefront the media buys were booked with. sellerName: nullable: true type: string mediaBuyIds: type: array items: type: string description: The seller's media buys in the campaign that were scored. delivery: type: object properties: value: nullable: true description: >- Did the seller deliver what was booked, on time? Ranked by distance from the even-pace line, so under- and over-delivery both rank lower. Null when the dimension is not reported for this seller; it then has no rank. type: object properties: spend: type: number description: >- Delivered spend, gross (fee-inclusive), in the response currency. budget: nullable: true description: >- Booked budget across the seller's media buys, gross. Null when any of them has no budget. type: number impressions: type: number minimum: 0 budgetDelivered: nullable: true description: spend divided by budget. Null without a budget. type: number minimum: 0 pace: nullable: true description: >- Spend pace across the buys that have a pace verdict. Null when none does: no budget or flight, or too little of the flight has run. type: object properties: expectedSpend: type: number description: >- Spend an even pace expects over the stretch of each buy's flight the period covers, summed across the seller's buys. actualSpend: type: number description: Spend delivered over those same stretches. ratio: type: number description: >- actualSpend divided by expectedSpend; 1 is exactly on pace. verdict: type: string enum: - on_pace - behind - ahead required: - expectedSpend - actualSpend - ratio - verdict additionalProperties: false required: - spend - budget - impressions - budgetDelivered - pace additionalProperties: false rank: nullable: true description: >- The seller's rank among the campaign's sellers on this dimension alone. 1 is best; tied values share a rank. Null when withheld. type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 rankedAmong: type: integer minimum: 0 maximum: 9007199254740991 description: How many of the campaign sellers were ranked on it. rankWithheld: nullable: true description: >- Why there is no rank: no value; a value over too few delivered units to compare; or no common yardstick (no budget and flight to pace against, no target, or sellers judged in different units). type: string enum: - not_reported - too_few_observations - not_comparable countedBy: nullable: true allOf: - $ref: '#/components/schemas/ScorecardCounter' required: - value - rank - rankedAmong - rankWithheld - countedBy additionalProperties: false description: >- Did the seller deliver what was booked, on time? Ranked by distance from the even-pace line, so under- and over-delivery both rank lower. price: type: object properties: value: nullable: true description: >- What the buyer paid per unit of the campaign's primary goal, or per thousand impressions when delivery cannot price the goal. Ranked cheapest first, once enough units were delivered to compare. Null when the dimension is not reported for this seller; it then has no rank. type: object properties: value: type: number minimum: 0 description: >- What the buyer paid per perUnits of unit: gross spend (fee-inclusive) divided by delivered units. unit: type: string enum: - impressions - clicks - views - completedViews - conversions - leads - viewableImpressions perUnits: anyOf: - type: number enum: - 1 - type: number enum: - 1000 units: type: number minimum: 0 exclusiveMinimum: true description: Delivered units the spend was divided by. currency: type: string required: - value - unit - perUnits - units - currency additionalProperties: false rank: nullable: true description: >- The seller's rank among the campaign's sellers on this dimension alone. 1 is best; tied values share a rank. Null when withheld. type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 rankedAmong: type: integer minimum: 0 maximum: 9007199254740991 description: How many of the campaign sellers were ranked on it. rankWithheld: nullable: true description: >- Why there is no rank: no value; a value over too few delivered units to compare; or no common yardstick (no budget and flight to pace against, no target, or sellers judged in different units). type: string enum: - not_reported - too_few_observations - not_comparable countedBy: nullable: true allOf: - $ref: '#/components/schemas/ScorecardCounter' required: - value - rank - rankedAmong - rankWithheld - countedBy additionalProperties: false description: >- What the buyer paid per unit of the campaign's primary goal, or per thousand impressions when delivery cannot price the goal. Ranked cheapest first, once enough units were delivered to compare. performance: type: object properties: value: nullable: true description: >- Goal progress over the seller's media buys together. Present with verdictWithheld when the goal's metric was not reported, so the reason is visible. Ranked only on a judged goal, by its achieved value. Null when the dimension is not reported for this seller; it then has no rank. allOf: - $ref: '#/components/schemas/GoalProgress' rank: nullable: true description: >- The seller's rank among the campaign's sellers on this dimension alone. 1 is best; tied values share a rank. Null when withheld. type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 rankedAmong: type: integer minimum: 0 maximum: 9007199254740991 description: How many of the campaign sellers were ranked on it. rankWithheld: nullable: true description: >- Why there is no rank: no value; a value over too few delivered units to compare; or no common yardstick (no budget and flight to pace against, no target, or sellers judged in different units). type: string enum: - not_reported - too_few_observations - not_comparable countedBy: nullable: true allOf: - $ref: '#/components/schemas/ScorecardCounter' required: - value - rank - rankedAmong - rankWithheld - countedBy additionalProperties: false description: >- Goal progress over the seller's media buys together. Present with verdictWithheld when the goal's metric was not reported, so the reason is visible. Ranked only on a judged goal, by its achieved value. quality: type: object properties: value: nullable: true description: >- Was the delivery viewable, valid and brand safe? Not judged yet, so always not reported. Null when the dimension is not reported for this seller; it then has no rank. type: string enum: - null rank: nullable: true description: >- The seller's rank among the campaign's sellers on this dimension alone. 1 is best; tied values share a rank. Null when withheld. type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 rankedAmong: type: integer minimum: 0 maximum: 9007199254740991 description: How many of the campaign sellers were ranked on it. rankWithheld: nullable: true description: >- Why there is no rank: no value; a value over too few delivered units to compare; or no common yardstick (no budget and flight to pace against, no target, or sellers judged in different units). type: string enum: - not_reported - too_few_observations - not_comparable countedBy: nullable: true allOf: - $ref: '#/components/schemas/ScorecardCounter' required: - value - rank - rankedAmong - rankWithheld - countedBy additionalProperties: false description: >- Was the delivery viewable, valid and brand safe? Not judged yet, so always not reported. required: - storefrontId - sellerName - mediaBuyIds - delivery - price - performance - quality additionalProperties: false ReportingMoneyCoverage: type: object properties: status: type: string enum: - complete - partial - unavailable description: >- complete when no gap is proven between stored reporting days; partial when a stored reporting day is missing between two present days; unavailable when no reporting data is stored. reason: nullable: true description: >- Why the money total is partial or unavailable. Null only when coverage is complete. type: string enum: - missing_reporting_days - no_reporting_data missingDays: type: integer minimum: 0 maximum: 9007199254740991 description: >- Number of proven gaps between stored reporting days in the requested range. required: - status - reason - missingDays additionalProperties: false description: Whether monetary reporting totals cover every requested media-buy day. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object ScorecardCounter: oneOf: - type: object properties: kind: type: string enum: - seller required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - vendor vendor: type: object properties: domain: type: string brandId: type: string required: - domain additionalProperties: false required: - kind - vendor additionalProperties: false - type: object properties: kind: type: string enum: - buyer_event_source vendor: type: object properties: domain: type: string brandId: type: string required: - domain additionalProperties: false required: - kind - vendor additionalProperties: false description: >- Who counted the value: the seller, in its own delivery report; a measurement vendor, whose values the seller reported; or the buyer's own event source, through its measurement records. type: object GoalProgress: type: object properties: goal: nullable: true description: >- The buyer's goal being judged: the commitment's asked goal, else the campaign's primary goal. Null when only a fixed outcome price is on record. type: object properties: kind: type: string enum: - metric - event - vendor_metric subject: type: string description: >- The metric name for a metric goal; the event type(s) joined with | for an event goal; `:` for a vendor metric goal. eventTypes: type: array items: type: string target: nullable: true allOf: - $ref: '#/components/schemas/GoalProgressTarget' vendor: description: >- The measurement vendor that counts a vendor metric goal. Absent for any other goal. type: object properties: domain: type: string brandId: type: string required: - domain additionalProperties: false metricId: description: >- The vendor's metric id for a vendor metric goal. Absent for any other goal. type: string required: - kind - subject - eventTypes - target additionalProperties: false askedTarget: nullable: true description: The target the buyer asked for, when the goal carries one. allOf: - $ref: '#/components/schemas/GoalProgressTarget' answeredTarget: nullable: true description: >- The cost or return the seller's terms commit or aim at, from the media buy's goal commitment. allOf: - $ref: '#/components/schemas/GoalProgressTarget' commitment: nullable: true description: >- The commitment kind on the media buy, or the weakest across a campaign; null when no buy carries one. type: string enum: - guaranteed - best_effort - report_only commitmentSource: nullable: true description: >- Where a media buy commitment came from; null at campaign level, where buys may differ. type: string enum: - proposal - campaign actual: nullable: true description: >- The achieved cost per unit (per thousand for impressions), rate over the metric's own denominator, or volume for the goal's metric, computed from the same delivery this response reports. Null when the metric was not reported or has no observations. type: object properties: kind: type: string enum: - cost_per - threshold_rate - volume value: type: number unit: type: string enum: - impressions - clicks - views - completedViews - conversions - leads - viewableImpressions - vendorMetric description: >- The delivery count the value is in. vendorMetric is a vendor metric goal's own metric: the vendor's value per measured impression when sellers reported it, or the advertiser's measured outcomes per delivered impression. units: type: number minimum: 0 description: >- The delivered count of the goal's unit the value was computed over; for a vendor metric goal, the impressions the vendor measured, or the outcomes the advertiser's records count. denominatorUnits: nullable: true description: >- What a threshold_rate divided by: measurable impressions for a viewable rate or a vendor metric, impressions for every other rate. Null for a cost or a volume. type: number minimum: 0 perUnits: anyOf: - type: number enum: - 1 - type: number enum: - 1000 description: >- How many units a cost_per value prices: 1000 for impressions (a price per thousand, like CPM), 1 for every other unit. currency: nullable: true type: string required: - kind - value - unit - units - denominatorUnits - perUnits - currency additionalProperties: false verdict: nullable: true description: >- How delivery compares with the target. Null whenever the evidence does not support a verdict; see verdictWithheld. type: string enum: - on_track - behind - beat judgedAgainst: nullable: true description: >- Which target the verdict compares against: the buyer's asked target, or the seller's answered price when the buyer stated none. type: string enum: - asked - answered verdictWithheld: nullable: true description: >- Why there is no verdict. metric_unsupported covers metrics delivery does not carry (reach, attention), event goals other than lead-only ones and return-on-ad-spend targets, which need event-scoped counts this surface does not have, and a cost target on a vendor metric goal, whose unit the vendor defines. It also covers vendor values reported under more than one qualifier, when the goal names none, or in windows that overlap without one containing the other. Too few observations means the metric is real but below the minimum count that makes a comparison meaningful. type: string enum: - no_goal - no_target - metric_unsupported - metric_not_reported - too_few_observations basis: nullable: true description: >- Who counted the number: seller_attested for the seller's own delivery counts, vendor_attested for a measurement vendor's values the seller reported under a vendor metric goal's vendor and metric id, advertiser_measured for the advertiser's own measurement records under that vendor and metric, which take precedence. oneOf: - type: object properties: kind: type: string enum: - seller_attested required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - advertiser_measured vendor: type: object properties: domain: type: string brandId: type: string required: - domain additionalProperties: false metricId: type: string impressions: type: number minimum: 0 description: >- Impressions delivered on the days the advertiser's measurement records cover, the rate's denominator. required: - kind - vendor - metricId - impressions additionalProperties: false - type: object properties: kind: type: string enum: - vendor_attested vendor: type: object properties: domain: type: string brandId: type: string required: - domain additionalProperties: false metricId: type: string measurableImpressions: type: number minimum: 0 description: Impressions the vendor measured across the values judged. coverage: nullable: true description: >- Share of delivered impressions the vendor measured, 0 to 1. Null when delivery reported no impressions to compare with. type: number minimum: 0 maximum: 1 required: - kind - vendor - metricId - measurableImpressions - coverage additionalProperties: false type: object freshness: type: object properties: dataThrough: nullable: true type: string reportingPeriodEnd: nullable: true type: string nextExpectedAt: nullable: true type: string notificationType: nullable: true type: string sequenceNumber: nullable: true type: number awaitingLaterReport: type: boolean missingMetrics: type: array items: type: string required: - dataThrough - reportingPeriodEnd - nextExpectedAt - notificationType - sequenceNumber - awaitingLaterReport - missingMetrics additionalProperties: false pace: nullable: true description: >- How the money is pacing against the flight, judged separately from the goal itself, so "$200 a day at 80% viewable" reads as two answers. Null when the surface does not know this scope's budget and flight. allOf: - $ref: '#/components/schemas/DeliveryPace' required: - goal - askedTarget - answeredTarget - commitment - commitmentSource - actual - verdict - judgedAgainst - verdictWithheld - basis - freshness - pace additionalProperties: false description: >- How delivery compares with the buyer's goal: the goal and targets, the seller's commitment, the achieved value, a verdict only when the evidence supports one, who counted the number, and how fresh it is. GoalProgressTarget: oneOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false description: >- A goal target: a cost per unit, a minimum rate per impression, a minimum return on ad spend, or maximise with no number. type: object DeliveryPace: type: object properties: flightElapsed: nullable: true description: >- Fraction of the WHOLE flight elapsed at the measured instant, 0 to 1. This says where the buy is in its life; it is not what expectedSpend is computed from on a windowed read. type: number measuredFraction: nullable: true description: >- Fraction of the flight the reported spend actually covers. Equal to flightElapsed when the read covers the buy's whole life, smaller when it covers a selected window — and it is this, not flightElapsed, that expectedSpend and the verdict are measured over, so both sides of the ratio always describe the same interval. type: number expectedSpend: nullable: true description: >- The spend an even pace across the flight expects over the interval the reported spend covers. type: number actualSpend: nullable: true description: The delivered spend the expectation is compared against. type: number ratio: nullable: true description: >- actualSpend divided by expectedSpend; 1 sits exactly on the even-pace line. type: number spendPerDay: nullable: true description: >- Delivered spend per day of the measured interval — the number a "$200 a day" ask names. type: number budgetPerDay: nullable: true description: The daily rate an even pace across the whole flight implies. type: number currency: nullable: true type: string verdict: nullable: true description: >- How delivered spend compares with the even-pace line. Null whenever the evidence does not support a verdict; see verdictWithheld. `ahead` is neither praise nor alarm — it means the flight will exhaust early at this rate. type: string enum: - on_pace - behind - ahead verdictWithheld: nullable: true description: >- Why there is no pace verdict: no booked budget, no usable flight window, the flight has not started, the reporting window you asked for covers none of the flight (reading a recent window of a flight that ended months ago), the reported spend covers too little of the flight for the ratio to mean anything, or no delivery has been reported. type: string enum: - no_budget - no_flight - flight_not_started - window_outside_flight - too_short_a_window - spend_not_reported required: - flightElapsed - measuredFraction - expectedSpend - actualSpend - ratio - spendPerDay - budgetPerDay - currency - verdict - verdictWithheld additionalProperties: false description: >- Delivered spend measured against how much of the buy's flight has run, rather than against its budget alone. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.