Function getMediaBuysResponse

Parameters

• data: {
      context?: Omit<Omit<{}, "bank">, "authentication"> & {
          authentication?: unknown;
      };
      governance_context?: string;
      media_buys: {
          media_buy_id: string;
          account?: {
              account_id: string;
              name: string;
              advertiser?: string;
              billing_proxy?: string;
              status: AccountStatus;
              brand?: {
                  domain: string;
                  brand_id?: string;
                  industries?: string[];
                  data_subject_contestation?: {
                      url?: string;
                      email?: string;
                      languages?: (...)[];
                  };
                  brand_kit_override?: {
                      logo?: {
                          asset_type: ...;
                          url: ...;
                          width: ...;
                          height: ...;
                          format?: ...;
                          alt_text?: ...;
                          provenance?: ...;
                      };
                      colors?: { primary?: ...; secondary?: ...; accent?: ... };
                      voice?: string;
                      tagline?: string;
                  };
              };
              operator?: string;
              billing?: BillingParty;
              billing_entity?: Omit<
                  {
                      legal_name: string;
                      vat_id?: string;
                      tax_id?: string;
                      registration_number?: string;
                      address?: {
                          street: string;
                          city: string;
                          postal_code: string;
                          region?: (...)
                          | (...);
                          country: string;
                      };
                      contacts?: { role: ...; name?: ...; email?: ...; phone?: ... }[];
                      bank?: {
                          account_holder: string;
                          iban?: (...) | (...);
                          bic?: (...) | (...);
                          routing_number?: (...) | (...);
                          account_number?: (...) | (...);
                      };
                      ext?: Omit<(...), (...)> & { authentication?: ... };
                  },
                  "bank",
              >;
              rate_card?: string;
              payment_terms?: PaymentTerms;
              credit_limit?: { amount: number; currency: string };
              setup?: { url?: string; message: string; expires_at?: string };
              account_scope?: AccountScope;
              governance_agents?: { url: string }[];
              reporting_bucket?: {
                  protocol: CloudStorageProtocol;
                  bucket: string;
                  prefix?: string;
                  region?: string;
                  format?: "jsonl" | "csv" | "parquet" | "avro" | "orc";
                  compression?: "gzip" | "none";
                  file_retention_days: number;
                  setup_instructions?: string;
              };
              sandbox?: boolean;
              notification_configs?: (
                  Omit<
                      {
                          subscriber_id: string;
                          url: string;
                          event_types: (...)[];
                          authentication?: (...) | (...);
                          active?: (...) | (...) | (...);
                          ext?: (...) | (...);
                      },
                      "authentication",
                  > & { authentication?: Omit<(...), (...)> }
              )[];
              ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
          };
          invoice_recipient?: Omit<
              {
                  legal_name: string;
                  vat_id?: string;
                  tax_id?: string;
                  registration_number?: string;
                  address?: {
                      street: string;
                      city: string;
                      postal_code: string;
                      region?: string;
                      country: string;
                  };
                  contacts?: {
                      role: "billing"
                      | "legal"
                      | "creative"
                      | "general";
                      name?: string;
                      email?: string;
                      phone?: string;
                  }[];
                  bank?: {
                      account_holder: string;
                      iban?: string;
                      bic?: string;
                      routing_number?: string;
                      account_number?: string;
                  };
                  ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                      authentication?: unknown;
                  };
              },
              "bank",
          >;
          status: MediaBuyStatus;
          status_as_of?: string
          | null;
          health?: "ok" | "impaired";
          impairments?: {
              impairment_id: string;
              resource_type:
                  | "creative"
                  | "audience"
                  | "catalog_item"
                  | "event_source"
                  | "property";
              resource_id: string;
              package_ids: string[];
              transition: { from?: string; to: ImpairmentOfflineState };
              reason_code: ImpairmentReasonCode;
              reason?: string;
              observed_at: string;
              remediation?: string;
          }[];
          rejection_reason?: string;
          currency: string;
          total_budget?: number;
          start_time?: string;
          end_time?: string;
          creative_deadline?: string;
          confirmed_at?: string
          | null;
          cancellation?: {
              canceled_at: string;
              canceled_by: CanceledBy;
              reason?: string;
          };
          revision?: number;
          created_at?: string;
          updated_at?: string;
          context?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
          valid_actions?: MediaBuyValidAction[];
          available_actions?: {
              action: MediaBuyValidAction;
              mode: MediaBuyActionMode;
              sla?: { response_max?: string; completion_max?: string };
              terms_ref?: string;
          }[];
          webhook_activity?: {
              idempotency_key: string;
              subscriber_id?: string;
              fired_at: string;
              completed_at?: string
              | null;
              notification_type: NotificationType;
              sequence_number?: number;
              attempt: number;
              status: "pending" | "failed" | "success" | "timeout" | "connection_error";
              url: string;
              http_status_code?: number | null;
              response_time_ms?: number | null;
              payload_size_bytes?: number;
              error_message?: string | null;
              ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
          }[];
          history?: {
              revision: number;
              timestamp: string;
              actor?: string;
              action: string;
              summary?: string;
              package_id?: string;
              ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
          }[];
          packages: {
              package_id: string;
              product_id?: string;
              budget?: number;
              currency?: string;
              bid_price?: number;
              format_ids?: {
                  agent_url: string;
                  id: string;
                  width?: number;
                  height?: number;
                  duration_ms?: number;
              }[];
              format_option_refs?: (
                  | {
                      scope: "publisher";
                      publisher_domain: string;
                      format_option_id: string;
                  }
                  | {
                      scope: "product";
                      format_option_id: string;
                      publisher_domain?: undefined;
                  }
              )[];
              format_kind?: CanonicalFormatKind;
              params?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
              impressions?: number;
              targeting_overlay?: {
                  geo_countries?: string[];
                  geo_countries_exclude?: string[];
                  geo_regions?: string[];
                  geo_regions_exclude?: string[];
                  geo_metros?: { system: MetroAreaSystem; values: (...)[] }[];
                  geo_metros_exclude?: { system: MetroAreaSystem; values: (...)[] }[];
                  geo_postal_areas?: (
                      | { country: ...; system: ...; values: ... }
                      | { system: ...; values: ... }
                  )[];
                  geo_postal_areas_exclude?: (
                      | { country: ...; system: ...; values: ... }
                      | { system: ...; values: ... }
                  )[];
                  daypart_targets?: {
                      days: (...)[];
                      start_hour: number;
                      end_hour: number;
                      label?: (...) | (...);
                  }[];
                  axe_include_segment?: string;
                  axe_exclude_segment?: string;
                  audience_include?: string[];
                  audience_exclude?: string[];
                  signal_targeting_groups?: {
                      operator: "all";
                      groups: { operator: ...; signals: ... }[];
                  };
                  signal_targeting?: (
                      | { signal_ref?: ...; signal_id?: ...; value_type: ...; value: ... }
                      | { signal_ref?: ...; signal_id?: ...; value_type: ...; values: ... }
                      | {
                          signal_ref?: ...;
                          signal_id?: ...;
                          value_type: ...;
                          min_value?: ...;
                          max_value?: ...;
                      }
                  )[];
                  frequency_cap?: {
                      suppress?: { interval: ...; unit: ... };
                      suppress_minutes?: number;
                      max_impressions?: number;
                      per?: ReachUnit;
                      window?: { interval: ...; unit: ... };
                  };
                  property_list?: {
                      agent_url: string;
                      list_id: string;
                      auth_token?: string;
                  };
                  collection_list?: {
                      agent_url: string;
                      list_id: string;
                      auth_token?: string;
                  };
                  collection_list_exclude?: {
                      agent_url: string;
                      list_id: string;
                      auth_token?: string;
                  };
                  age_restriction?: {
                      min: number;
                      verification_required?: boolean;
                      accepted_methods?: (...)[];
                  };
                  device_platform?: DevicePlatform[];
                  device_type?: DeviceType[];
                  device_type_exclude?: DeviceType[];
                  store_catchments?: {
                      catalog_id: string;
                      store_ids?: (...)
                      | (...);
                      catchment_ids?: (...) | (...);
                  }[];
                  geo_proximity?: (
                      | {
                          lat: ...;
                          lng: ...;
                          label?: ...;
                          travel_time: ...;
                          transport_mode: ...;
                          ext?: ...;
                      }
                      | {
                          lat: ...;
                          lng: ...;
                          label?: ...;
                          transport_mode?: ...;
                          radius: ...;
                          ext?: ...;
                      }
                      | {
                          lat?: ...;
                          lng?: ...;
                          label?: ...;
                          transport_mode?: ...;
                          geometry: ...;
                          ext?: ...;
                      }
                  )[];
                  language?: string[];
                  keyword_targets?: {
                      keyword: string;
                      match_type: MatchType;
                      bid_price?: (...)
                      | (...);
                  }[];
                  negative_keywords?: { keyword: string; match_type: MatchType }[];
              };
              start_time?: string;
              end_time?: string;
              paused?: boolean;
              canceled?: boolean;
              cancellation?: {
                  canceled_at: string;
                  canceled_by: CanceledBy;
                  reason?: string;
              };
              creative_deadline?: string;
              context?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
              creative_approvals?: {
                  creative_id: string;
                  approval_status?: CreativeApprovalStatus;
                  rejection_reason?: string;
              }[];
              format_ids_pending?: {
                  agent_url: string;
                  id: string;
                  width?: number;
                  height?: number;
                  duration_ms?: number;
              }[];
              snapshot_unavailable_reason?: SnapshotUnavailableReason;
              snapshot?: {
                  as_of: string;
                  staleness_seconds: number;
                  impressions: number;
                  spend: number;
                  currency?: string;
                  clicks?: number;
                  pacing_index?: number;
                  delivery_status?: | "completed"
                  | "delivering"
                  | "budget_exhausted"
                  | "flight_ended"
                  | "goal_met"
                  | "not_delivering";
                  ext?: Omit<Omit<(...), (...)>, "authentication"> & {
                      authentication?: unknown;
                  };
              };
              ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
          }[];
          ext?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
      }[];
      errors?: {
          code: string;
          message: string;
          field?: string;
          suggestion?: string;
          retry_after?: number;
          issues?: {
              pointer: string;
              message: string;
              keyword: string;
              schemaPath?: string;
              schema_id?: string;
              discriminator?: {
                  property_name: string;
                  value: (...)
                  | (...)
                  | (...)
                  | (...)
                  | (...);
              }[];
          }[];
          details?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
          recovery?: "transient"
          | "correctable"
          | "terminal";
          source?: "producer" | "sdk";
          sdk_id?: string;
      }[];
      pagination?: { has_more: boolean; cursor?: string; total_count?: number };
      sandbox?: boolean;
      ext?: Omit<Omit<{}, "bank">, "authentication"> & {
          authentication?: unknown;
      };
  }

  • Optionalcontext?: Omit<Omit<{}, "bank">, "authentication"> & { authentication?: unknown }

  • Optionalgovernance_context?: string

    Governance context token issued by the account's governance agent during check_governance. Buyers attach it to governed purchase requests (media buys, rights acquisitions, signal activations, creative services); sellers persist it and include it on all subsequent governance calls for that action's lifecycle. An account binds to one governance agent (see sync_governance); governance is phased across purchase / modification / delivery, not partitioned across specialist agents, so the envelope carries a single token for the full lifecycle.

    Value format: governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged. In 3.1 all sellers MUST verify. Non-JWS values from pre-3.0 governance agents are deprecated.

    This is the primary correlation key for audit and reporting across the governance lifecycle.

  • media_buys: {
        media_buy_id: string;
        account?: {
            account_id: string;
            name: string;
            advertiser?: string;
            billing_proxy?: string;
            status: AccountStatus;
            brand?: {
                domain: string;
                brand_id?: string;
                industries?: string[];
                data_subject_contestation?: {
                    url?: string;
                    email?: string;
                    languages?: (...)[];
                };
                brand_kit_override?: {
                    logo?: {
                        asset_type: ...;
                        url: ...;
                        width: ...;
                        height: ...;
                        format?: ...;
                        alt_text?: ...;
                        provenance?: ...;
                    };
                    colors?: { primary?: ...; secondary?: ...; accent?: ... };
                    voice?: string;
                    tagline?: string;
                };
            };
            operator?: string;
            billing?: BillingParty;
            billing_entity?: Omit<
                {
                    legal_name: string;
                    vat_id?: string;
                    tax_id?: string;
                    registration_number?: string;
                    address?: {
                        street: string;
                        city: string;
                        postal_code: string;
                        region?: (...)
                        | (...);
                        country: string;
                    };
                    contacts?: { role: ...; name?: ...; email?: ...; phone?: ... }[];
                    bank?: {
                        account_holder: string;
                        iban?: (...) | (...);
                        bic?: (...) | (...);
                        routing_number?: (...) | (...);
                        account_number?: (...) | (...);
                    };
                    ext?: Omit<(...), (...)> & { authentication?: ... };
                },
                "bank",
            >;
            rate_card?: string;
            payment_terms?: PaymentTerms;
            credit_limit?: { amount: number; currency: string };
            setup?: { url?: string; message: string; expires_at?: string };
            account_scope?: AccountScope;
            governance_agents?: { url: string }[];
            reporting_bucket?: {
                protocol: CloudStorageProtocol;
                bucket: string;
                prefix?: string;
                region?: string;
                format?: "jsonl" | "csv" | "parquet" | "avro" | "orc";
                compression?: "gzip" | "none";
                file_retention_days: number;
                setup_instructions?: string;
            };
            sandbox?: boolean;
            notification_configs?: (
                Omit<
                    {
                        subscriber_id: string;
                        url: string;
                        event_types: (...)[];
                        authentication?: (...) | (...);
                        active?: (...) | (...) | (...);
                        ext?: (...) | (...);
                    },
                    "authentication",
                > & { authentication?: Omit<(...), (...)> }
            )[];
            ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
        };
        invoice_recipient?: Omit<
            {
                legal_name: string;
                vat_id?: string;
                tax_id?: string;
                registration_number?: string;
                address?: {
                    street: string;
                    city: string;
                    postal_code: string;
                    region?: string;
                    country: string;
                };
                contacts?: {
                    role: "billing"
                    | "legal"
                    | "creative"
                    | "general";
                    name?: string;
                    email?: string;
                    phone?: string;
                }[];
                bank?: {
                    account_holder: string;
                    iban?: string;
                    bic?: string;
                    routing_number?: string;
                    account_number?: string;
                };
                ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                    authentication?: unknown;
                };
            },
            "bank",
        >;
        status: MediaBuyStatus;
        status_as_of?: string
        | null;
        health?: "ok" | "impaired";
        impairments?: {
            impairment_id: string;
            resource_type:
                | "creative"
                | "audience"
                | "catalog_item"
                | "event_source"
                | "property";
            resource_id: string;
            package_ids: string[];
            transition: { from?: string; to: ImpairmentOfflineState };
            reason_code: ImpairmentReasonCode;
            reason?: string;
            observed_at: string;
            remediation?: string;
        }[];
        rejection_reason?: string;
        currency: string;
        total_budget?: number;
        start_time?: string;
        end_time?: string;
        creative_deadline?: string;
        confirmed_at?: string
        | null;
        cancellation?: {
            canceled_at: string;
            canceled_by: CanceledBy;
            reason?: string;
        };
        revision?: number;
        created_at?: string;
        updated_at?: string;
        context?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
        valid_actions?: MediaBuyValidAction[];
        available_actions?: {
            action: MediaBuyValidAction;
            mode: MediaBuyActionMode;
            sla?: { response_max?: string; completion_max?: string };
            terms_ref?: string;
        }[];
        webhook_activity?: {
            idempotency_key: string;
            subscriber_id?: string;
            fired_at: string;
            completed_at?: string
            | null;
            notification_type: NotificationType;
            sequence_number?: number;
            attempt: number;
            status: "pending" | "failed" | "success" | "timeout" | "connection_error";
            url: string;
            http_status_code?: number | null;
            response_time_ms?: number | null;
            payload_size_bytes?: number;
            error_message?: string | null;
            ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
        }[];
        history?: {
            revision: number;
            timestamp: string;
            actor?: string;
            action: string;
            summary?: string;
            package_id?: string;
            ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
        }[];
        packages: {
            package_id: string;
            product_id?: string;
            budget?: number;
            currency?: string;
            bid_price?: number;
            format_ids?: {
                agent_url: string;
                id: string;
                width?: number;
                height?: number;
                duration_ms?: number;
            }[];
            format_option_refs?: (
                | {
                    scope: "publisher";
                    publisher_domain: string;
                    format_option_id: string;
                }
                | {
                    scope: "product";
                    format_option_id: string;
                    publisher_domain?: undefined;
                }
            )[];
            format_kind?: CanonicalFormatKind;
            params?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
            impressions?: number;
            targeting_overlay?: {
                geo_countries?: string[];
                geo_countries_exclude?: string[];
                geo_regions?: string[];
                geo_regions_exclude?: string[];
                geo_metros?: { system: MetroAreaSystem; values: (...)[] }[];
                geo_metros_exclude?: { system: MetroAreaSystem; values: (...)[] }[];
                geo_postal_areas?: (
                    | { country: ...; system: ...; values: ... }
                    | { system: ...; values: ... }
                )[];
                geo_postal_areas_exclude?: (
                    | { country: ...; system: ...; values: ... }
                    | { system: ...; values: ... }
                )[];
                daypart_targets?: {
                    days: (...)[];
                    start_hour: number;
                    end_hour: number;
                    label?: (...) | (...);
                }[];
                axe_include_segment?: string;
                axe_exclude_segment?: string;
                audience_include?: string[];
                audience_exclude?: string[];
                signal_targeting_groups?: {
                    operator: "all";
                    groups: { operator: ...; signals: ... }[];
                };
                signal_targeting?: (
                    | { signal_ref?: ...; signal_id?: ...; value_type: ...; value: ... }
                    | { signal_ref?: ...; signal_id?: ...; value_type: ...; values: ... }
                    | {
                        signal_ref?: ...;
                        signal_id?: ...;
                        value_type: ...;
                        min_value?: ...;
                        max_value?: ...;
                    }
                )[];
                frequency_cap?: {
                    suppress?: { interval: ...; unit: ... };
                    suppress_minutes?: number;
                    max_impressions?: number;
                    per?: ReachUnit;
                    window?: { interval: ...; unit: ... };
                };
                property_list?: {
                    agent_url: string;
                    list_id: string;
                    auth_token?: string;
                };
                collection_list?: {
                    agent_url: string;
                    list_id: string;
                    auth_token?: string;
                };
                collection_list_exclude?: {
                    agent_url: string;
                    list_id: string;
                    auth_token?: string;
                };
                age_restriction?: {
                    min: number;
                    verification_required?: boolean;
                    accepted_methods?: (...)[];
                };
                device_platform?: DevicePlatform[];
                device_type?: DeviceType[];
                device_type_exclude?: DeviceType[];
                store_catchments?: {
                    catalog_id: string;
                    store_ids?: (...)
                    | (...);
                    catchment_ids?: (...) | (...);
                }[];
                geo_proximity?: (
                    | {
                        lat: ...;
                        lng: ...;
                        label?: ...;
                        travel_time: ...;
                        transport_mode: ...;
                        ext?: ...;
                    }
                    | {
                        lat: ...;
                        lng: ...;
                        label?: ...;
                        transport_mode?: ...;
                        radius: ...;
                        ext?: ...;
                    }
                    | {
                        lat?: ...;
                        lng?: ...;
                        label?: ...;
                        transport_mode?: ...;
                        geometry: ...;
                        ext?: ...;
                    }
                )[];
                language?: string[];
                keyword_targets?: {
                    keyword: string;
                    match_type: MatchType;
                    bid_price?: (...)
                    | (...);
                }[];
                negative_keywords?: { keyword: string; match_type: MatchType }[];
            };
            start_time?: string;
            end_time?: string;
            paused?: boolean;
            canceled?: boolean;
            cancellation?: {
                canceled_at: string;
                canceled_by: CanceledBy;
                reason?: string;
            };
            creative_deadline?: string;
            context?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
            creative_approvals?: {
                creative_id: string;
                approval_status?: CreativeApprovalStatus;
                rejection_reason?: string;
            }[];
            format_ids_pending?: {
                agent_url: string;
                id: string;
                width?: number;
                height?: number;
                duration_ms?: number;
            }[];
            snapshot_unavailable_reason?: SnapshotUnavailableReason;
            snapshot?: {
                as_of: string;
                staleness_seconds: number;
                impressions: number;
                spend: number;
                currency?: string;
                clicks?: number;
                pacing_index?: number;
                delivery_status?: | "completed"
                | "delivering"
                | "budget_exhausted"
                | "flight_ended"
                | "goal_met"
                | "not_delivering";
                ext?: Omit<Omit<(...), (...)>, "authentication"> & {
                    authentication?: unknown;
                };
            };
            ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
        }[];
        ext?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
    }[]

    Array of media buys with status, creative approval state, and optional delivery snapshots

  • Optionalerrors?: {
        code: string;
        message: string;
        field?: string;
        suggestion?: string;
        retry_after?: number;
        issues?: {
            pointer: string;
            message: string;
            keyword: string;
            schemaPath?: string;
            schema_id?: string;
            discriminator?: {
                property_name: string;
                value: (...) | (...) | (...) | (...) | (...);
            }[];
        }[];
        details?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
        recovery?: "transient"
        | "correctable"
        | "terminal";
        source?: "producer" | "sdk";
        sdk_id?: string;
    }[]

    Task-specific errors (e.g., media buy not found)

  • Optionalpagination?: { has_more: boolean; cursor?: string; total_count?: number }

    • has_more: boolean

      Whether more results are available beyond this page

    • Optionalcursor?: string

      Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true.

    • Optionaltotal_count?: number

      Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this.

      Minimum

      0

  • Optionalsandbox?: boolean

    When true, this response contains simulated data from sandbox mode.

  • Optionalext?: Omit<Omit<{}, "bank">, "authentication"> & { authentication?: unknown }

• Optionalsummary: string