> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Get one buy's exchange timeline > The seller-scoped projection of the buy's exchange record: stages (received → screened → decided → forwarded / forward-failed → submitted → source moderation → accepted / rejected → delivering) with evidence, per-source legs, and the references to quote per state — the source's own ids as their reference, and the `sf:` idempotency key paired with the request timestamp as the platform reference. The forwarded payload is returned minus platform-internal fields (webhook/push-notification config and signing material); admin-only material never appears. `{"pruned": true}` payloads mean retention removed the bytes. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml get /media-buys/{mediaBuyId}/timeline openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: |- REST API for partners to manage storefronts, 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: 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 storefronts - name: AI Usage description: Storefront AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /media-buys/{mediaBuyId}/timeline: get: tags: - Storefront summary: Get one buy's exchange timeline description: >- The seller-scoped projection of the buy's exchange record: stages (received → screened → decided → forwarded / forward-failed → submitted → source moderation → accepted / rejected → delivering) with evidence, per-source legs, and the references to quote per state — the source's own ids as their reference, and the `sf:` idempotency key paired with the request timestamp as the platform reference. The forwarded payload is returned minus platform-internal fields (webhook/push-notification config and signing material); admin-only material never appears. `{"pruned": true}` payloads mean retention removed the bytes. operationId: getStorefrontMediaBuyTimeline parameters: - in: path name: mediaBuyId schema: description: Media buy id at the storefront grain (`sf_mb_…`). type: string minLength: 1 required: true description: Media buy id at the storefront grain (`sf_mb_…`). responses: '200': description: Get one buy's exchange timeline content: application/json: schema: $ref: '#/components/schemas/StorefrontMediaBuyTimelineResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The buy does not exist on this storefront (unknown id, or a buy belonging to another storefront). 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: StorefrontMediaBuyTimelineResponse: description: >- The seller-scoped projection of a buy's exchange timeline: only this storefront's legs; forwarded/response payloads minus platform-internal fields; no admin-only material (resolution cache internals, worker poll internals, cross-tenant audit rows). type: object properties: mediaBuyId: type: string buyer: type: object properties: customerId: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 name: nullable: true type: string required: - customerId - name additionalProperties: false approval: description: The approval-queue row, when the buy rode the review flow. nullable: true type: object properties: status: type: string submittedAt: type: string reviewedBy: nullable: true type: string reviewedAt: nullable: true type: string reviewerNotes: nullable: true type: string forwardedAt: nullable: true type: string submittedPayload: description: >- The buyer's submitted payload as it sits in the approval queue (already webhook-credential-free), minus platform-internal fields. nullable: true type: object additionalProperties: {} required: - status - submittedAt - reviewedBy - reviewedAt - reviewerNotes - forwardedAt - submittedPayload additionalProperties: false stages: description: >- Buy-level stages (pre-fan-out): received, screened, decided, and any pre-dispatch failure. type: array items: $ref: '#/components/schemas/SellerTimelineStage' legs: type: array items: $ref: '#/components/schemas/SellerTimelineLeg' eventsTruncated: description: >- True when more ledger events exist than were hydrated into this timeline. type: boolean required: - mediaBuyId - buyer - approval - stages - legs - eventsTruncated additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false SellerTimelineStage: description: One reached stage of the exchange, with evidence. type: object properties: stage: $ref: '#/components/schemas/SellerTimelineStageName' at: description: >- When the buy entered this stage (ISO 8601). Null when the stage is inferred without a precise timestamp. nullable: true type: string detail: description: >- Human-readable note — the reviewer decision, the sanitized source moderation message, the failure summary. nullable: true type: string evidence: description: Supporting observations, newest first. type: array items: $ref: '#/components/schemas/SellerTimelineEvidence' required: - stage - at - detail - evidence additionalProperties: false SellerTimelineLeg: description: One source leg of the buy, as seen from the storefront. type: object properties: sourceId: type: string sourceName: nullable: true type: string sourceKind: type: string currentStatus: description: Latest persisted upstream status for this leg. nullable: true type: string forwardedAt: nullable: true type: string responseReceivedAt: nullable: true type: string theirReference: description: >- The source's own ids for this exchange — quote these to the source; they can look them up directly. type: object properties: mediaBuyId: nullable: true type: string taskId: nullable: true type: string required: - mediaBuyId - taskId additionalProperties: false platformReference: description: >- The Scope3 reference for this exchange: the create idempotency key (`sf:::`) paired with the request timestamp. Quote both together — the key is stable across the buy’s life, requests are not. type: object properties: idempotencyKey: nullable: true type: string requestedAt: nullable: true type: string required: - idempotencyKey - requestedAt additionalProperties: false stages: description: Stages this leg reached, lifecycle order. type: array items: $ref: '#/components/schemas/SellerTimelineStage' forwardedPayload: description: >- The exact AdCP request sent to this source, minus platform-internal fields (webhook/push-notification config and signing material are projected out server-side). `{"pruned": true}` when retention removed the payload. nullable: true type: object additionalProperties: {} responsePayload: description: >- The source's latest response as persisted, minus platform-internal fields. `{"pruned": true}` when retention removed the payload. nullable: true type: object additionalProperties: {} payloadHighlights: description: >- Trafficker-grade summary of the forwarded payload; null when nothing was forwarded. nullable: true allOf: - $ref: '#/components/schemas/SellerPayloadHighlights' replayed: description: >- True when the captured response was an idempotency-cache replay — a historical snapshot, not current state. nullable: true type: boolean note: description: >- Structural note (e.g. "the forward never succeeded — no route exists for this source"). nullable: true type: string required: - sourceId - sourceName - sourceKind - currentStatus - forwardedAt - responseReceivedAt - theirReference - platformReference - stages - forwardedPayload - responsePayload - payloadHighlights - replayed - note additionalProperties: false ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false SellerTimelineStageName: description: >- Lifecycle stage of a buy exchange as seen from the storefront: received → screened → decided → forwarded / forward-failed → submitted → source moderation → accepted / rejected → delivering. Update exchanges reuse the same stages. `screened` is RESERVED for the acceptance-policy pre-screen record and is not emitted today — do not wait for it. type: string enum: - received - screened - decided - forwarded - forward_failed - submitted - source_moderation - accepted - rejected - delivering SellerTimelineEvidence: description: One observed fact supporting a timeline stage. type: object properties: at: description: When it happened (ISO 8601). type: string kind: description: >- exchange_event = one attempt/response/poll observation; webhook = an inbound source webhook receipt; collapsed_run = N near-identical repeated events elided (retry loops). type: string enum: - exchange_event - webhook - collapsed_run eventType: description: >- Ledger event type (attempt_started, request_sent, response_received, precondition_failed, poll_result, webhook_received, terminalized). nullable: true type: string outcome: nullable: true type: string errorCode: description: Structured error code when the exchange failed. nullable: true type: string recovery: description: >- Recovery class of a failure: transient (retry can succeed), correctable (fix the input and resubmit), structural (no retry can succeed — escalate). nullable: true type: string enum: - transient - correctable - structural attemptNumber: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 hiddenCount: description: 'For collapsed_run: how many near-identical events were elided.' nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 detail: description: Short human-readable note (webhook type, poll status, …). nullable: true type: string required: - at - kind - eventType - outcome - errorCode - recovery - attemptNumber - hiddenCount - detail additionalProperties: false SellerPayloadHighlights: description: >- Trafficker-grade highlights extracted from the forwarded payload: flight, budget, packages, targeting dimensions. type: object properties: flightStart: nullable: true type: string flightEnd: nullable: true type: string budget: nullable: true type: number currency: nullable: true type: string packageCount: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 productIds: description: Product ids referenced by the packages (first 20). type: array items: type: string targetingKeys: description: Top-level targeting dimensions present in the request (keys only). type: array items: type: string required: - flightStart - flightEnd - budget - currency - packageCount - productIds - targetingKeys additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````