> ## 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 storefront reporting > Get reporting metrics for every media buy the Merchandising Agent participates in through the Storefront inventory sources. The Storefront does not own the underlying media buys; reporting is visible because the Merchandising Agent is the ADCP party to those transactions. The response is hierarchical for view=summary, source-aware flat leaf-by-day rows for view=timeseries, or a signed CSV download descriptor when download=true. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml get /reporting/metrics openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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.interchange.io/api/v2/storefront description: Production server security: [] tags: - 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: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /reporting/metrics: get: tags: - Reporting summary: Get storefront reporting description: >- Get reporting metrics for every media buy the Merchandising Agent participates in through the Storefront inventory sources. The Storefront does not own the underlying media buys; reporting is visible because the Merchandising Agent is the ADCP party to those transactions. The response is hierarchical for view=summary, source-aware flat leaf-by-day rows for view=timeseries, or a signed CSV download descriptor when download=true. operationId: getStorefrontReportingMetrics parameters: - in: query name: inventorySourceId schema: description: >- Filter to media buys flowing through a single inventory source (storefront_inventory_source.source_id). When omitted, includes every inventory source on the storefront. type: string description: >- Filter to media buys flowing through a single inventory source (storefront_inventory_source.source_id). When omitted, includes every inventory source on the storefront. - in: query name: startDate schema: description: Start date in ISO format (YYYY-MM-DD) example: '2026-01-01' type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Start date in ISO format (YYYY-MM-DD) - in: query name: endDate schema: description: End date in ISO format (YYYY-MM-DD) example: '2026-01-31' type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: End date in ISO format (YYYY-MM-DD) - in: query name: days schema: default: 7 description: 'Number of days to include (default: 7, min: 1, max: 90).' example: 7 type: integer minimum: 1 maximum: 90 description: 'Number of days to include (default: 7, min: 1, max: 90).' - in: query name: view schema: default: summary description: >- Response format: "summary" for hierarchical advertiser/media-buy/package breakdown, "timeseries" for flat per-day rows. type: string enum: - summary - timeseries description: >- Response format: "summary" for hierarchical advertiser/media-buy/package breakdown, "timeseries" for flat per-day rows. - in: query name: download schema: description: >- When true, generates a CSV file and returns a signed download URL instead of JSON data default: false type: boolean description: >- When true, generates a CSV file and returns a signed download URL instead of JSON data - in: query name: demo schema: description: >- When true, returns auto-generated demo data instead of querying real data sources default: false type: boolean description: >- When true, returns auto-generated demo data instead of querying real data sources - in: query name: sourceBreakdown schema: description: >- When true, timeseries rows are split by each contributing inventory source. The default preserves the legacy media-buy/package/date row grain. default: 'false' type: string enum: - 'true' - 'false' description: >- When true, timeseries rows are split by each contributing inventory source. The default preserves the legacy media-buy/package/date row grain. responses: '200': description: Get storefront reporting content: application/json: schema: anyOf: - $ref: '#/components/schemas/StorefrontReportingMetricsResponse' - $ref: >- #/components/schemas/StorefrontReportingMetricsTimeseriesResponse - $ref: '#/components/schemas/ReportingMetricsExportResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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: StorefrontReportingMetricsResponse: type: object properties: advertisers: type: array items: $ref: '#/components/schemas/StorefrontAdvertiserReporting' description: Advertiser-level reporting data totals: description: Aggregated totals across all advertisers allOf: - $ref: '#/components/schemas/ReportingMetrics' periodStart: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Start of the reporting period (YYYY-MM-DD) periodEnd: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: End of the reporting period (YYYY-MM-DD) required: - advertisers - totals - periodStart - periodEnd additionalProperties: false description: >- Hierarchical storefront reporting response: advertiser → media buy → package StorefrontReportingMetricsTimeseriesResponse: type: object properties: timeseries: type: array items: $ref: '#/components/schemas/StorefrontTimeseriesEntry' description: >- Flat rows: one entry per (advertiser → media buy → package) × day, sorted by date ascending totals: description: Aggregated totals across the entire period allOf: - $ref: '#/components/schemas/ReportingMetrics' periodStart: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Start of the reporting period (YYYY-MM-DD) periodEnd: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: End of the reporting period (YYYY-MM-DD) required: - timeseries - totals - periodStart - periodEnd additionalProperties: false description: 'Time-series storefront reporting response: flat leaf × day rows' ReportingMetricsExportResponse: type: object properties: downloadUrl: type: string format: uri description: Signed URL to download the CSV file (expires in 7 days) expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp when the download URL expires fileName: type: string description: Name of the generated CSV file rowCount: type: integer minimum: 0 maximum: 9007199254740991 description: Number of data rows in the CSV (excluding header) required: - downloadUrl - expiresAt - fileName - rowCount additionalProperties: false description: Response containing a signed URL to download the exported CSV 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 StorefrontAdvertiserReporting: type: object properties: advertiserId: type: string description: Advertiser identifier advertiserName: type: string description: Advertiser name metrics: $ref: '#/components/schemas/ReportingMetrics' mediaBuys: type: array items: $ref: '#/components/schemas/StorefrontMediaBuyReporting' description: Media buy-level breakdown required: - advertiserId - advertiserName - metrics - mediaBuys additionalProperties: false description: >- Advertiser-level reporting metrics with media buy breakdown (no campaign level) ReportingMetrics: type: object properties: impressions: type: integer minimum: 0 maximum: 9007199254740991 description: Total impressions spend: type: number minimum: 0 description: >- Total spend, denominated in the advertiser's primary currency (every campaign and buy is stamped in that currency; USD only for USD advertisers). On BUYER surfaces spend is GROSS (fee-inclusive): seller-reported net delivered spend is grossed up at read time at each buy's own pinned terms (a buy without pinned terms reports net as stored). On STOREFRONT surfaces spend stays NET as the seller reported it. clicks: type: integer minimum: 0 maximum: 9007199254740991 description: Total clicks views: type: integer minimum: 0 maximum: 9007199254740991 description: >- Viewable impressions (the MRC-viewable subset of impressions, per AdCP). For viewability rate, divide by impressions. completedViews: type: integer minimum: 0 maximum: 9007199254740991 description: >- Video/audio completions (qualified by view_duration_seconds when set on the goal) conversions: type: integer minimum: 0 maximum: 9007199254740991 description: Total conversions leads: type: integer minimum: 0 maximum: 9007199254740991 description: Total leads videoCompletions: type: integer minimum: 0 maximum: 9007199254740991 description: Total video completions conversionValue: type: number minimum: 0 description: >- Total conversion value (advertiser-attributed revenue from conversions), denominated the same as spend. Unlike spend, conversion value is never grossed up on buyer surfaces — it is advertiser revenue, not marketplace spend, so it carries no platform fee. ecpm: nullable: true description: >- Effective CPM: (spend * 1000) / impressions, derived from spend in this surface's denomination (gross fee-inclusive on buyer surfaces); null when impressions is 0 type: number cpc: nullable: true description: >- Cost per click: spend / clicks, derived from spend in this surface's denomination (gross fee-inclusive on buyer surfaces); null when clicks is 0 type: number ctr: nullable: true description: 'Click-through rate: clicks / impressions' type: number completionRate: nullable: true description: >- Completion rate: completedViews / impressions (completions per paid impression; impressions is the paid unit for CPM video) type: number cpa: nullable: true description: >- Cost per acquisition: spend / conversions, derived from spend in this surface's denomination (gross fee-inclusive on buyer surfaces); null when conversions is 0 type: number roas: nullable: true description: >- Return on ad spend: conversionValue / spend; null when spend is 0, or when there is no conversion signal at all (conversionValue and conversions are both 0). Reports a true 0 when conversions are real but attributed value is zero. conversionValue carries no platform fee while spend is gross fee-inclusive on buyer surfaces, so buyer ROAS reads lower than storefront ROAS for identical delivery — the same denomination difference that already separates buyer and storefront cpc/ecpm. type: number required: - impressions - spend - clicks - views - completedViews - conversions - leads - videoCompletions - conversionValue - ecpm - cpc - ctr - completionRate - cpa - roas additionalProperties: false description: Raw and calculated reporting metrics StorefrontTimeseriesEntry: type: object properties: date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Reporting date (YYYY-MM-DD) example: '2026-01-15' advertiserId: type: string description: Advertiser identifier advertiserName: type: string description: Advertiser name mediaBuyId: type: string description: Media buy identifier mediaBuyName: type: string description: Media buy name mediaBuyStatus: type: string description: Media buy status inventorySourceId: type: string description: >- Deterministic legacy inventory-source association. With sourceBreakdown=true this is the contributing source; otherwise use inventorySourceIds for complete provenance. inventorySourceIds: type: array items: type: string description: >- Sorted distinct storefront inventory source IDs carried by the delivery rows aggregated into this result. packageId: type: string description: Package identifier. Empty string when the media buy has no packages. productId: type: string description: Product identifier for this package. Empty string when no package. productName: type: string description: >- Human-readable product name for this package. Empty string when no package. metrics: $ref: '#/components/schemas/ReportingMetrics' required: - date - advertiserId - advertiserName - mediaBuyId - mediaBuyName - mediaBuyStatus - inventorySourceId - inventorySourceIds - packageId - productId - productName - metrics additionalProperties: false description: >- One row of metrics for a single (advertiser → media buy → package) leaf on a single 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 StorefrontMediaBuyReporting: type: object properties: mediaBuyId: type: string description: Media buy identifier name: type: string description: Media buy name status: type: string description: Media buy status budget: nullable: true description: >- Total allocated budget for this media buy (sum of product budgets), null if no budget set type: number inventorySourceId: nullable: true description: >- Storefront inventory source this media buy flows through (storefront_inventory_source.source_id), or null when no source matched. type: string metrics: $ref: '#/components/schemas/ReportingMetrics' packages: type: array items: $ref: '#/components/schemas/StorefrontPackageReporting' description: Package-level breakdown required: - mediaBuyId - name - status - budget - inventorySourceId - metrics - packages additionalProperties: false description: Media buy-level reporting metrics with package breakdown StorefrontPackageReporting: type: object properties: packageId: type: string description: Package identifier productId: nullable: true description: Product identifier for this package type: string productName: nullable: true description: Human-readable product name for this package type: string metrics: $ref: '#/components/schemas/ReportingMetrics' required: - packageId - productId - productName - metrics additionalProperties: false description: Package-level reporting metrics securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````