Module `adcp.types.signals`

AdCP signals types — curated partial surface.

Signal types — discovery / activation, signal targeting, and audiences.

A stable, narrow alternative to importing the whole :mod:adcp.types namespace. Every name here is also exported from :mod:adcp.types; this module simply groups the ones a signals integration reaches for, and never exposes the internal generated layer.

This module is for curation and discoverability, not a separate performance tier: importing it is cheap, but the first access to any AdCP type (here or via :mod:adcp.types / :mod:adcp) realizes the full generated Pydantic graph — there is no per-domain graph. Use it for a smaller, focused import surface.

from adcp.types.signals import GetSignalsRequest

Classes

class ActivateSignalRequest (**data: Any)

Expand source code

class ActivateSignalRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    action: Annotated[
        Action | None,
        Field(
            description="Whether to activate or deactivate the signal. Deactivating removes the segment from downstream platforms, required when campaigns end to comply with data governance policies (GDPR, CCPA). Defaults to 'activate' when omitted."
        ),
    ] = Action.activate
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque activation handle returned in the signal_agent_segment_id field of each get_signals response entry. Pass this string verbatim — do not pass the signal_id object.'
        ),
    ]
    destinations: Annotated[
        list[destination.Destination],
        Field(
            description='Target destination(s) for activation. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ]
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="The pricing option selected from the signal's pricing_options in the get_signals response. Required when the signal has pricing options. Records the buyer's pricing commitment at activation time; pass this same value in report_usage for billing verification."
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this activation. Associates with a commercial relationship established via sync_accounts.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate activations on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : adcp.types.generated_poc.core.account_ref.AccountReference | None
var action : adcp.types.generated_poc.signals.activate_signal_request.Action | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var destinations : list[adcp.types.generated_poc.core.destination.Destination]
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var idempotency_key : str
var model_config
var pricing_option_id : str | None
var signal_agent_segment_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ActivateSignalSuccessResponse (**data: Any)

Expand source code

class ActivateSignalResponse1(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    deployments: list[deployment_1.Deployment]
    sandbox: bool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var deployments : list[adcp.types.generated_poc.core.deployment.Deployment]
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ActivateSignalErrorResponse (**data: Any)

Expand source code

class ActivateSignalResponse2(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error]
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SegmentIdActivationKey (**data: Any)

Expand source code

class ActivationKey1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['segment_id'], Field(description='Segment ID based targeting')] = 'segment_id'
    segment_id: Annotated[
        str,
        Field(description='The platform-specific segment identifier to use in campaign targeting'),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var segment_id : str
var type : Literal['segment_id']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class KeyValueActivationKey (**data: Any)

Expand source code

class ActivationKey2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['key_value'], Field(description='Key-value pair based targeting')] = 'key_value'
    key: Annotated[str, Field(description='The targeting parameter key')]
    value: Annotated[str, Field(description='The targeting parameter value')]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var key : str
var model_config
var type : Literal['key_value']
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesAudience (**data: Any)

Expand source code

class Audience(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    audience_id: Annotated[
        str,
        Field(
            description="Buyer's identifier for this audience. Used to reference the audience in targeting overlays."
        ),
    ]
    name: Annotated[str | None, Field(description='Human-readable name for this audience')] = None
    description: Annotated[
        str | None,
        Field(
            description="Human-readable description of this audience's composition or purpose (e.g., 'High-value customers who purchased in the last 90 days')."
        ),
    ] = None
    audience_type: Annotated[
        AudienceType | None,
        Field(
            description="Intended use for this audience. 'crm': target these users. 'suppression': exclude these users from delivery. 'lookalike_seed': use as a seed for the seller's lookalike modeling. Sellers may handle audiences differently based on type (e.g., suppression lists bypass minimum size requirements on some platforms)."
        ),
    ] = None
    tags: Annotated[
        list[Tag] | None,
        Field(
            description="Buyer-defined tags for organizing and filtering audiences (e.g., 'holiday_2026', 'high_ltv'). Tags are stored by the seller and returned in discovery-only calls."
        ),
    ] = None
    add: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to add to this audience. Hashed before sending — normalize emails to lowercase+trim, phones to E.164.',
            min_length=1,
        ),
    ] = None
    remove: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to remove from this audience. If the same identifier appears in both add and remove in a single request, remove takes precedence.',
            min_length=1,
        ),
    ] = None
    delete: Annotated[
        bool | None,
        Field(
            description='When true, delete this audience from the account entirely. All other fields on this audience object are ignored. Use this to delete a specific audience without affecting others.'
        ),
    ] = None
    consent_basis: Annotated[
        consent_basis_1.ConsentBasis | None,
        Field(
            description='GDPR lawful basis for processing this audience list. Informational — not validated by the protocol, but required by some sellers operating in regulated markets (e.g. EU). When omitted, the buyer asserts they have a lawful basis appropriate to their jurisdiction.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var add : list[adcp.types.generated_poc.core.audience_member.AudienceMember] | None
var audience_id : str
var audience_type : adcp.types.generated_poc.media_buy.sync_audiences_request.AudienceType | None
var consent_basis : adcp.types.generated_poc.enums.consent_basis.ConsentBasis | None
var delete : bool | None
var description : str | None
var model_config
var name : str | None
var remove : list[adcp.types.generated_poc.core.audience_member.AudienceMember] | None
var tags : list[adcp.types.generated_poc.media_buy.sync_audiences_request.Tag] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AudienceSource (*args, **kwds)

Expand source code

class AudienceSource(StrEnum):
    synced = 'synced'
    platform = 'platform'
    third_party = 'third_party'
    lookalike = 'lookalike'
    retargeting = 'retargeting'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var lookalike
var platform
var retargeting
var synced
var third_party
var unknown

class GetSignalsRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When consent_basis or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        int | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : adcp.types.generated_poc.core.account_ref.AccountReference | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var countries : list[adcp.types.generated_poc.signals.get_signals_request.Country] | None
var destinations : list[adcp.types.generated_poc.core.destination.Destination] | None
var discovery_mode : adcp.types.generated_poc.signals.get_signals_request.DiscoveryMode | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var fields : list[adcp.types.generated_poc.signals.get_signals_request.Field1] | None
var filters : adcp.types.generated_poc.core.signal_filters.SignalFilters | None
var if_pricing_version : str | None
var if_wholesale_feed_version : str | None
var max_results : int | None
var model_config
var pagination : adcp.types.generated_poc.core.pagination_request.PaginationRequest | None
var push_notification_config : adcp.types.generated_poc.core.push_notification_config.PushNotificationConfig | None
var signal_ids : list[adcp.types.generated_poc.core.signal_id.SignalId] | None
var signal_refs : list[adcp.types.generated_poc.core.signal_ref.SignalRef] | None
var signal_spec : str | None

class GetSignalsDiscoveryRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When consent_basis or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        int | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : adcp.types.generated_poc.core.account_ref.AccountReference | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var countries : list[adcp.types.generated_poc.signals.get_signals_request.Country] | None
var destinations : list[adcp.types.generated_poc.core.destination.Destination] | None
var discovery_mode : adcp.types.generated_poc.signals.get_signals_request.DiscoveryMode | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var fields : list[adcp.types.generated_poc.signals.get_signals_request.Field1] | None
var filters : adcp.types.generated_poc.core.signal_filters.SignalFilters | None
var if_pricing_version : str | None
var if_wholesale_feed_version : str | None
var max_results : int | None
var model_config
var pagination : adcp.types.generated_poc.core.pagination_request.PaginationRequest | None
var push_notification_config : adcp.types.generated_poc.core.push_notification_config.PushNotificationConfig | None
var signal_ids : list[adcp.types.generated_poc.core.signal_id.SignalId] | None
var signal_refs : list[adcp.types.generated_poc.core.signal_ref.SignalRef] | None
var signal_spec : str | None

class GetSignalsLookupRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When consent_basis or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        int | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : adcp.types.generated_poc.core.account_ref.AccountReference | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var countries : list[adcp.types.generated_poc.signals.get_signals_request.Country] | None
var destinations : list[adcp.types.generated_poc.core.destination.Destination] | None
var discovery_mode : adcp.types.generated_poc.signals.get_signals_request.DiscoveryMode | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var fields : list[adcp.types.generated_poc.signals.get_signals_request.Field1] | None
var filters : adcp.types.generated_poc.core.signal_filters.SignalFilters | None
var if_pricing_version : str | None
var if_wholesale_feed_version : str | None
var max_results : int | None
var model_config
var pagination : adcp.types.generated_poc.core.pagination_request.PaginationRequest | None
var push_notification_config : adcp.types.generated_poc.core.push_notification_config.PushNotificationConfig | None
var signal_ids : list[adcp.types.generated_poc.core.signal_id.SignalId] | None
var signal_refs : list[adcp.types.generated_poc.core.signal_ref.SignalRef] | None
var signal_spec : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[Sequence[Signal] | None, Field(description='Array of matching signals')] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the agent could not finish within the caller's time_budget or due to internal limits. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale signals feed state used to compose this response. Agents that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so callers can cache and probe later. Callers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A caller caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer. When the agent supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Agents not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the agent's published rate card; the caller MAY dedupe under (agent, discovery_mode, filters, destinations, countries) without scoping by account. 'account': this response includes account-specific overrides; the caller MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the agent MUST return `cache_scope: 'public'`. When the request included `account`, the agent MUST return either 'public' (this account prices off the public rate card — caller dedupes) or 'account' (account-specific overrides exist — caller caches under the account key). Agents MAY return 'public' on an account-scoped request that previously had overrides — callers SHOULD interpret this as a downgrade. Without schema-required cache_scope, an agent silently omitting the field on an account-scoped response would cause callers to mis-key the cache and serve account-overlay payloads to other accounts — the canonical safety invariant of the entire cache layering model. **Backward-compatibility note for 3.1 validators:** SDKs validating strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version`. For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed — pre-3.1 agents correctly emit no cache_scope and remain conformant to their declared version. This is a tightening within 3.1, not a 3.0 break."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the agent's current version for the caller's cache_scope, in which case signals[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Callers receiving unchanged: true MUST NOT mutate their local wholesale signals mirror. **One shape per state:** agents MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries signals."
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        bool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
adcp.types.generated_poc.core.protocol_envelope.ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_scope : adcp.types.generated_poc.signals.get_signals_response.CacheScope | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error] | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var incomplete : list[adcp.types.generated_poc.signals.get_signals_response.IncompleteItem] | None
var model_config
var pagination : adcp.types.generated_poc.core.pagination_response.PaginationResponse | None
var pricing_version : str | None
var sandbox : bool | None
var signals : collections.abc.Sequence[adcp.types.generated_poc.signals.get_signals_response.Signal] | None
var unchanged : Literal[True] | None
var wholesale_feed_version : str | None

class GetSignalsSuccessResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[Sequence[Signal] | None, Field(description='Array of matching signals')] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the agent could not finish within the caller's time_budget or due to internal limits. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale signals feed state used to compose this response. Agents that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so callers can cache and probe later. Callers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A caller caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer. When the agent supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Agents not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the agent's published rate card; the caller MAY dedupe under (agent, discovery_mode, filters, destinations, countries) without scoping by account. 'account': this response includes account-specific overrides; the caller MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the agent MUST return `cache_scope: 'public'`. When the request included `account`, the agent MUST return either 'public' (this account prices off the public rate card — caller dedupes) or 'account' (account-specific overrides exist — caller caches under the account key). Agents MAY return 'public' on an account-scoped request that previously had overrides — callers SHOULD interpret this as a downgrade. Without schema-required cache_scope, an agent silently omitting the field on an account-scoped response would cause callers to mis-key the cache and serve account-overlay payloads to other accounts — the canonical safety invariant of the entire cache layering model. **Backward-compatibility note for 3.1 validators:** SDKs validating strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version`. For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed — pre-3.1 agents correctly emit no cache_scope and remain conformant to their declared version. This is a tightening within 3.1, not a 3.0 break."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the agent's current version for the caller's cache_scope, in which case signals[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Callers receiving unchanged: true MUST NOT mutate their local wholesale signals mirror. **One shape per state:** agents MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries signals."
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        bool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
adcp.types.generated_poc.core.protocol_envelope.ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_scope : adcp.types.generated_poc.signals.get_signals_response.CacheScope | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error] | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var incomplete : list[adcp.types.generated_poc.signals.get_signals_response.IncompleteItem] | None
var model_config
var pagination : adcp.types.generated_poc.core.pagination_response.PaginationResponse | None
var pricing_version : str | None
var sandbox : bool | None
var signals : collections.abc.Sequence[adcp.types.generated_poc.signals.get_signals_response.Signal] | None
var unchanged : Literal[True] | None
var wholesale_feed_version : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsSubmittedResponse (**data: Any)

Expand source code

class GetSignalsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose signals array is issued in-line. See task-status.json for the full task-status enum.'
        ),
    ] = 'submitted'
    task_id: Annotated[
        str,
        Field(
            description='Task handle the caller uses with tasks/get, and that the agent references on push-notification callbacks. The signals array is issued on the completion artifact, not here. Per AdCP wire conventions this is snake_case; A2A adapters MAY surface it as taskId, but the payload field emitted by the agent is task_id.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description="Optional human-readable explanation of why the task is submitted — e.g., 'Provider discovery queued; typical turnaround 10-30 minutes.' Plain text only. Callers MUST treat this as untrusted agent input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile agent may inject prompt-injection payloads aimed at the caller's agent.",
            max_length=2000,
        ),
    ] = None
    estimated_completion: Annotated[
        AwareDatetime | None,
        Field(description='Estimated completion time for the signal discovery task.'),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories or partial provider unavailability). Terminal failures belong in the error branch, not here.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error] | None
var estimated_completion : pydantic.types.AwareDatetime | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var message : str | None
var model_config
var status : Literal['submitted']
var task_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsWorkingResponse (**data: Any)

Expand source code

class GetSignalsWorking(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    percentage: Annotated[
        float | None,
        Field(
            description='Progress percentage of the signal discovery operation.', ge=0.0, le=100.0
        ),
    ] = None
    current_step: Annotated[
        str | None,
        Field(
            description='Current step in the signal discovery process, such as `querying_providers`, `ranking_signals`, or `checking_deployments`.'
        ),
    ] = None
    total_steps: Annotated[
        int | None, Field(description='Total number of steps in the signal discovery process.')
    ] = None
    step_number: Annotated[int | None, Field(description='Current step number (1-indexed).')] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var current_step : str | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var model_config
var percentage : float | None
var step_number : int | None
var total_steps : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PackageSignalTargeting (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PackageSignalTargeting(
    RootModel[PackageSignalTargeting5 | PackageSignalTargeting6 | PackageSignalTargeting7]
):
    root: Annotated[
        PackageSignalTargeting5 | PackageSignalTargeting6 | PackageSignalTargeting7,
        Field(
            description="Buy-time selection of one seller-offered signal inside a package signal targeting group. The signal_ref uses scope 'product' for a product-local signal option, scope 'data_provider' for a signal defined in a data provider's published adagents.json signals[], or scope 'signal_source' for a source-native signal that is not published in adagents.json signals[]. The selected product's inline Product.signal_targeting_options, get_signals feed when inline options are omitted, and signal_targeting_rules define buy-time eligibility. Inclusion and exclusion are controlled by the parent group operator: use operator 'any' to include users matching the signal expression and operator 'none' to exclude users matching the signal expression. For binary signals, value MUST be true; do not use value=false for exclusion inside signal_targeting_groups. Use audience_include/audience_exclude only for buyer-managed first-party audiences registered through sync_audiences.",
            title='Package Signal Targeting',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[PackageSignalTargeting5, PackageSignalTargeting6, PackageSignalTargeting7]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : adcp.types.generated_poc.core.package_signal_targeting.PackageSignalTargeting5 | adcp.types.generated_poc.core.package_signal_targeting.PackageSignalTargeting6 | adcp.types.generated_poc.core.package_signal_targeting.PackageSignalTargeting7

class PackageSignalTargetingGroup (**data: Any)

Expand source code

class PackageSignalTargetingGroup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    operator: Annotated[
        Operator,
        Field(
            description="How to evaluate the signals in this group. 'any' is an OR include group. 'none' is an exclusion group equivalent to NOT (A OR B OR C)."
        ),
    ]
    signals: Annotated[
        list[package_signal_targeting.PackageSignalTargeting],
        Field(
            description='Signal targeting entries evaluated by this group. Each entry uses the package signal targeting shape, including signal_ref, value expression, and optional pricing, execution-handle, or activation fields.',
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var operator : adcp.types.generated_poc.core.package_signal_targeting_group.Operator
var signals : list[adcp.types.generated_poc.core.package_signal_targeting.PackageSignalTargeting]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PackageSignalTargetingGroups (**data: Any)

Expand source code

class PackageSignalTargetingGroups(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    operator: Annotated[
        Literal['all'],
        Field(
            description="Groups-level operator. Required even though v1 only supports 'all': every child group must be satisfied."
        ),
    ] = 'all'
    groups: Annotated[
        list[package_signal_targeting_group.PackageSignalTargetingGroup],
        Field(
            description="Signal targeting groups to evaluate. Use operator 'any' for include groups and 'none' for exclusion groups.",
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var groups : list[adcp.types.generated_poc.core.package_signal_targeting_group.PackageSignalTargetingGroup]
var model_config
var operator : Literal['all']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductSignalTargetingOption (**data: Any)

Expand source code

class ProductSignalTargetingOption(SignalListing):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_agent_segment_id: Annotated[
        str | None,
        Field(
            description='Optional opaque resolved-segment or seller execution handle for this signal. Omit when signal_ref plus the value expression is sufficient for the seller to resolve the signal. Include when the seller exposes a distinct runtime or activation handle that buyers must echo in packages[].targeting_overlay.signal_targeting_groups.groups[].signals[].signal_agent_segment_id. Buyers SHOULD echo this handle verbatim rather than reconstructing identity from categorical values; providers MAY namespace handles so cross-provider identity stays legible without a shared taxonomy registry.'
        ),
    ] = None
    activation_status: Annotated[
        ActivationStatus | None,
        Field(
            description="Whether this signal option is ready to select on create_media_buy for the requesting account. 'ready' means the buyer can select it directly. 'requires_activation' means the buyer must activate the signal first or include an activation_key the seller accepts."
        ),
    ] = ActivationStatus.ready
    allowed_targeting_modes: Annotated[
        list[AllowedTargetingMode] | None,
        Field(
            description="How this signal may be used when composing package-level signal targeting groups. 'include' means the signal may appear in an 'any' child group. 'exclude' means the signal may appear in a 'none' child group. Omit when the signal is include-only. This field declares the allowed buy-time group operator; binary package signal entries still use value=true in both include and exclude groups.",
            min_length=1,
        ),
    ] = [AllowedTargetingMode.include]
    default_selected: Annotated[
        bool | None,
        Field(
            description="Whether the seller recommends or preselects this signal when composing this product. Buyers may remove it unless signal_targeting_rules.selection_mode is 'fixed'. When selection_mode is 'fixed', sellers apply default_selected signals even if the buyer omits signal_targeting_groups and MUST echo the applied entries on the resulting package state."
        ),
    ] = False
    selection_group: Annotated[
        str | None,
        Field(
            description='Optional product-defined composability bucket for signal options, such as alternative audience tiers, a key-value targeting plane, or an audience-segment targeting plane. Signals in the same selection_group are expected to be OR-combinable inside one child group for a given targeting mode, subject to signal_targeting_rules. Use different selection_group values when the product requires separate ANDed clauses, such as signal sets backed by different platform targeting primitives that cannot be collapsed into one child group. selection_group is a product-option grouping key, not a reference to one child object in packages[].targeting_overlay.signal_targeting_groups.groups[]. Sellers can use signal_targeting_rules.max_selected_per_group and signal_targeting_rules.selection_group_rules with selection_group to guide and validate storefront composition.'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Signal pricing options available when this signal is selected on this product. Product-scoped pricing is authoritative for this product; if get_signals exposes a different default rate card, use this product-scoped price when composing the buy. Buyers pass the selected pricing_option_id in packages[].targeting_overlay.signal_targeting_groups.groups[].signals[].pricing_option_id. Omit when the signal is bundled into the product price or has no incremental cost.',
            min_length=1,
        ),
    ] = None
    signal_ref: Annotated[
        signal_ref.SignalRef,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.signal_listing.SignalListing
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var activation_status : adcp.types.generated_poc.core.product_signal_targeting_option.ActivationStatus | None
var allowed_targeting_modes : list[adcp.types.generated_poc.core.product_signal_targeting_option.AllowedTargetingMode] | None
var default_selected : bool | None
var model_config
var pricing_options : list[adcp.types.generated_poc.core.vendor_pricing_option.VendorPricingOption] | None
var selection_group : str | None
var signal_agent_segment_id : str | None
var signal_ref : adcp.types.generated_poc.core.signal_ref.SignalRef

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsSignal (**data: Any)

Expand source code

class Signal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older Signals Protocol clients.',
        ),
    ] = None
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque resolved-segment handle issued by this signal source. Pass this string verbatim to activate_signal.signal_agent_segment_id, and echo it in package signal targeting when the selected product option exposes the same handle. Treat the value as provider-scoped and opaque: providers MAY namespace it so two providers can expose similarly named signals without relying on a shared taxonomy. Do not pass the signal_id object as this handle, and do not reconstruct a segment handle from categorical values when get_signals returned a resolved segment.'
        ),
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable signal name. Required when signal_ref_1.scope is 'product'. For data_provider and signal_source refs, this is optional contextual display text; the referenced definition or source remains authoritative."
        ),
    ]
    description: Annotated[
        str,
        Field(
            description='Detailed signal description. For data_provider and signal_source refs, this is optional contextual display text and MUST NOT replace the referenced definition.'
        ),
    ]
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(
            description="The data type of this signal's values. Required when signal_ref_1.scope is 'product'."
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'.",
            min_length=1,
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None
    signal_type: Annotated[
        signal_catalog_type.SignalAvailabilityType,
        Field(description='Commercial/provenance type of signal (marketplace, custom, owned)'),
    ]
    data_provider: Annotated[
        str | None,
        Field(
            description='Human-readable source name for the signal, when applicable. For data_provider-scoped signals this is the data provider name; for signal_source-scoped signals it may identify the signal source or proprietary origin.'
        ),
    ] = None
    coverage_percentage: Annotated[
        float | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only. If coverage_forecast includes an absent bucket over the same denominator, coverage_percentage SHOULD align with 100 * (1 - absent coverage_rate.mid).',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance. When present, this is authoritative for signal-level discovery coverage. Use this to disclose the denominator, bucket semantics, not-present bucket, aggregate present bucket, and per-value coverage distribution for the signal.'
        ),
    ] = None
    deployments: Annotated[
        Sequence[deployment.Deployment], Field(description='Array of deployment targets')
    ]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options available for this signal when it has an incremental price. The buyer selects one and passes its pricing_option_id in report_usage or package-level signal_targeting_groups for billing verification. Omit when pricing is unavailable to the caller, bundled into the destination product, or has no incremental cost.',
            min_length=1,
        ),
    ] = None
    methodology_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this definition record was last updated. This indicates freshness of the definition record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(description='Restricted attribute categories this signal touches.', min_length=1),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(description='Policy categories this signal is sensitive for.', min_length=1),
    ] = None
    taxonomy: Annotated[
        Taxonomy | None,
        Field(
            description='Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.'
        ),
    ] = None
    segmentation_criteria: Annotated[str | None, Field(max_length=500)] = None
    criteria_url: AnyUrl | None = None
    data_sources: Annotated[list[DataSource] | None, Field(min_length=1)] = None
    methodology: Methodology | None = None
    audience_expansion: bool | None = None
    device_expansion: bool | None = None
    refresh_cadence: RefreshCadence | None = None
    lookback_window: RefreshCadence | None = None
    onboarder: Onboarder | None = None
    countries: Annotated[list[Country] | None, Field(min_length=1)] = None
    consent_basis: Annotated[
        list[consent_basis_1.ConsentBasis] | None,
        Field(
            description="Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.",
            min_length=1,
        ),
    ] = None
    art9_basis: Annotated[
        Art9Basis | None,
        Field(
            description="Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis."
        ),
    ] = None
    modeling: Modeling | None = None
    data_subject_rights: Annotated[
        DataSubjectRights | None,
        Field(
            description='Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.'
        ),
    ] = None
    dts_compliant_version: str | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var art9_basis : adcp.types.generated_poc.signals.get_signals_response.Art9Basis | None
var audience_expansion : bool | None
var categories : list[str] | None
var consent_basis : list[adcp.types.generated_poc.enums.consent_basis.ConsentBasis] | None
var countries : list[adcp.types.generated_poc.signals.get_signals_response.Country] | None
var coverage_forecast : adcp.types.generated_poc.core.signal_coverage_forecast.SignalCoverageForecast | None
var coverage_percentage : float | None
var criteria_url : pydantic.networks.AnyUrl | None
var data_provider : str | None
var data_sources : list[adcp.types.generated_poc.signals.get_signals_response.DataSource] | None
var data_subject_rights : adcp.types.generated_poc.signals.get_signals_response.DataSubjectRights | None
var deployments : Sequence[adcp.types.generated_poc.core.deployment.Deployment]
var description : str
var device_expansion : bool | None
var dts_compliant_version : str | None
var last_updated : pydantic.types.AwareDatetime | None
var lookback_window : adcp.types.generated_poc.signals.get_signals_response.RefreshCadence | None
var methodology : adcp.types.generated_poc.signals.get_signals_response.Methodology | None
var methodology_url : pydantic.networks.AnyUrl | None
var model_config
var modeling : adcp.types.generated_poc.signals.get_signals_response.Modeling | None
var name : str
var onboarder : adcp.types.generated_poc.signals.get_signals_response.Onboarder | None
var policy_categories : list[str] | None
var pricing_options : list[adcp.types.generated_poc.core.vendor_pricing_option.VendorPricingOption] | None
var range : adcp.types.generated_poc.signals.get_signals_response.Range | None
var refresh_cadence : adcp.types.generated_poc.signals.get_signals_response.RefreshCadence | None
var restricted_attributes : list[adcp.types.generated_poc.enums.restricted_attribute.RestrictedAttribute] | None
var segmentation_criteria : str | None
var signal_agent_segment_id : str
var signal_id : adcp.types.generated_poc.core.signal_id.SignalId | None
var signal_ref : adcp.types.generated_poc.core.signal_ref.SignalRef | None
var signal_type : adcp.types.generated_poc.enums.signal_catalog_type.SignalAvailabilityType
var taxonomy : adcp.types.generated_poc.signals.get_signals_response.Taxonomy | None
var value_type : adcp.types.generated_poc.enums.signal_value_type.SignalValueType | None

class Signal (**data: Any)

Expand source code

class Signal(SignalListing):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description='Canonical signal reference for this wholesale signal. New events SHOULD use signal_ref.'
        ),
    ] = None
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older clients.',
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(description='Opaque activation handle returned by the signals agent.', min_length=1),
    ]
    name: Annotated[str, Field(description='Human-readable signal name', min_length=1)]
    description: Annotated[str, Field(description='Detailed signal description', min_length=1)]
    value_type: signal_value_type.SignalValueType | None = None
    categories: Annotated[list[str] | None, Field(min_length=1)] = None
    range: Range | None = None
    signal_type: signal_catalog_type.SignalAvailabilityType
    data_provider: Annotated[str | None, Field(min_length=1)] = None
    coverage_percentage: Annotated[
        float | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance using the same wire shape as get_signals.signals[].coverage_forecast. When present, this is authoritative for signal-level discovery coverage.'
        ),
    ] = None
    deployments: Annotated[Sequence[deployment.Deployment], Field(min_length=1)]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None, Field(min_length=1)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.signal_listing.SignalListing
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var categories : list[str] | None
var coverage_forecast : adcp.types.generated_poc.core.signal_coverage_forecast.SignalCoverageForecast | None
var coverage_percentage : float | None
var data_provider : str | None
var deployments : Sequence[adcp.types.generated_poc.core.deployment.Deployment]
var description : str
var model_config
var name : str
var pricing_options : list[adcp.types.generated_poc.core.vendor_pricing_option.VendorPricingOption] | None
var range : adcp.types.generated_poc.core.signal_listing.Range | None
var signal_agent_segment_id : str
var signal_id : adcp.types.generated_poc.core.signal_id.SignalId | None
var signal_ref : adcp.types.generated_poc.core.signal_ref.SignalRef | None
var signal_type : adcp.types.generated_poc.enums.signal_catalog_type.SignalAvailabilityType
var value_type : adcp.types.generated_poc.enums.signal_value_type.SignalValueType | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalAvailabilityType (*args, **kwds)

Expand source code

class SignalAvailabilityType(StrEnum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var custom
var marketplace
var owned

class SignalCatalogType (*args, **kwds)

Expand source code

class SignalAvailabilityType(StrEnum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var custom
var marketplace
var owned

class SignalDefinitionEnrichment (**data: Any)

Expand source code

class SignalDefinitionEnrichment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(description='Restricted attribute categories this signal touches.', min_length=1),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(description='Policy categories this signal is sensitive for.', min_length=1),
    ] = None
    taxonomy: Annotated[
        Taxonomy | None,
        Field(
            description='Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.'
        ),
    ] = None
    segmentation_criteria: Annotated[str | None, Field(max_length=500)] = None
    criteria_url: AnyUrl | None = None
    data_sources: Annotated[list[DataSource] | None, Field(min_length=1)] = None
    methodology: Methodology | None = None
    audience_expansion: bool | None = None
    device_expansion: bool | None = None
    refresh_cadence: RefreshCadence | None = None
    lookback_window: RefreshCadence | None = None
    onboarder: Onboarder | None = None
    countries: Annotated[list[Country] | None, Field(min_length=1)] = None
    consent_basis: Annotated[
        list[consent_basis_1.ConsentBasis] | None,
        Field(
            description="Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.",
            min_length=1,
        ),
    ] = None
    art9_basis: Annotated[
        Art9Basis | None,
        Field(
            description="Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis."
        ),
    ] = None
    modeling: Modeling | None = None
    data_subject_rights: Annotated[
        DataSubjectRights | None,
        Field(
            description='Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this definition record was last updated. This indicates freshness of the definition record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    dts_compliant_version: str | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var art9_basis : adcp.types.generated_poc.core.signal_definition_enrichment.Art9Basis | None
var audience_expansion : bool | None
var consent_basis : list[adcp.types.generated_poc.enums.consent_basis.ConsentBasis] | None
var countries : list[adcp.types.generated_poc.core.signal_definition_enrichment.Country] | None
var criteria_url : pydantic.networks.AnyUrl | None
var data_sources : list[adcp.types.generated_poc.core.signal_definition_enrichment.DataSource] | None
var data_subject_rights : adcp.types.generated_poc.core.signal_definition_enrichment.DataSubjectRights | None
var device_expansion : bool | None
var dts_compliant_version : str | None
var last_updated : pydantic.types.AwareDatetime | None
var lookback_window : adcp.types.generated_poc.core.signal_definition_enrichment.RefreshCadence | None
var methodology : adcp.types.generated_poc.core.signal_definition_enrichment.Methodology | None
var model_config
var modeling : adcp.types.generated_poc.core.signal_definition_enrichment.Modeling | None
var onboarder : adcp.types.generated_poc.core.signal_definition_enrichment.Onboarder | None
var policy_categories : list[str] | None
var refresh_cadence : adcp.types.generated_poc.core.signal_definition_enrichment.RefreshCadence | None
var restricted_attributes : list[adcp.types.generated_poc.enums.restricted_attribute.RestrictedAttribute] | None
var segmentation_criteria : str | None
var taxonomy : adcp.types.generated_poc.core.signal_definition_enrichment.Taxonomy | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalFilters (**data: Any)

Expand source code

class SignalFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_types: Annotated[
        list[signal_catalog_type.SignalAvailabilityType] | None,
        Field(description='Filter by catalog type', min_length=1),
    ] = None
    data_providers: Annotated[
        list[str] | None, Field(description='Filter by specific data providers', min_length=1)
    ] = None
    max_cpm: Annotated[
        float | None,
        Field(description="Maximum CPM filter. Applies only to signals with model='cpm'.", ge=0.0),
    ] = None
    max_percent: Annotated[
        float | None,
        Field(
            description='Maximum percent-of-media rate filter. Signals where all percent_of_media pricing options exceed this value are excluded. Does not account for max_cpm caps.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    min_coverage_percentage: Annotated[
        float | None, Field(description='Minimum coverage requirement', ge=0.0, le=100.0)
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Vendor-namespaced extension parameters for seller- or platform-specific signal filter criteria not covered by standard fields. Keys MUST be namespaced under a vendor or platform key (e.g., ext.gam, ext.platform_x). Sellers MUST treat all values as untrusted buyer input; avoid unbounded logging or labels, and do not interpolate values into caller-visible error strings, LLM prompts, SQL queries, or system commands without sanitization. Persistent use of an extension key across multiple buyers is a signal to propose standardization.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_types : list[adcp.types.generated_poc.enums.signal_catalog_type.SignalAvailabilityType] | None
var data_providers : list[str] | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var max_cpm : float | None
var max_percent : float | None
var min_coverage_percentage : float | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalListing (**data: Any)

Expand source code

class SignalListing(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ] = None
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older Signals Protocol clients.',
        ),
    ] = None
    name: Annotated[
        str | None,
        Field(
            description="Human-readable signal name. Required when signal_ref.scope is 'product'. For data_provider and signal_source refs, this is optional contextual display text; the referenced definition or source remains authoritative."
        ),
    ] = None
    description: Annotated[
        str | None,
        Field(
            description='Detailed signal description. For data_provider and signal_source refs, this is optional contextual display text and MUST NOT replace the referenced definition.'
        ),
    ] = None
    methodology_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this listing record was last updated. This indicates freshness of the listing record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(
            description="The data type of this signal's values. Required when signal_ref.scope is 'product'."
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'.",
            min_length=1,
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

adcp.types.generated_poc.core.product_signal_targeting_option.ProductSignalTargetingOption
adcp.types.generated_poc.core.wholesale_feed_event.Signal

Class variables

var categories : list[str] | None
var description : str | None
var last_updated : pydantic.types.AwareDatetime | None
var methodology_url : pydantic.networks.AnyUrl | None
var model_config
var name : str | None
var range : adcp.types.generated_poc.core.signal_listing.Range | None
var signal_id : adcp.types.generated_poc.core.signal_id.SignalId | None
var signal_ref : adcp.types.generated_poc.core.signal_ref.SignalRef | None
var value_type : adcp.types.generated_poc.enums.signal_value_type.SignalValueType | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalPricingOption (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalPricingOption(RootModel[vendor_pricing_option.VendorPricingOption]):
    root: Annotated[
        vendor_pricing_option.VendorPricingOption,
        Field(
            description='Deprecated — use vendor-pricing-option.json for new implementations. This alias is retained for backward compatibility.',
            title='Signal Pricing Option',
        ),
    ]

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[VendorPricingOption]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : adcp.types.generated_poc.core.vendor_pricing_option.VendorPricingOption

class SignalRef (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalRef(RootModel[SignalRef106 | SignalRef107 | SignalRef108]):
    root: Annotated[
        SignalRef106 | SignalRef107 | SignalRef108,
        Field(
            description="Reference to a named signal definition. Uses scope as discriminator: 'data_provider' for a signal resolved through published adagents.json signals[], 'signal_source' for a source-native signal resolved through the issuing signal source, or 'product' for a product-local signal option. Scope is the resolution path, not provenance; authoritative enrichment lives on the seller, signal source, or data-provider signal definition, not on this reference.",
            discriminator='scope',
            title='Signal Ref',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[SignalRef106, SignalRef107, SignalRef108]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : adcp.types.generated_poc.core.signal_ref.SignalRef106 | adcp.types.generated_poc.core.signal_ref.SignalRef107 | adcp.types.generated_poc.core.signal_ref.SignalRef108

class SignalTargeting (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalTargeting(RootModel[SignalTargeting9 | SignalTargeting10 | SignalTargeting11]):
    root: Annotated[
        SignalTargeting9 | SignalTargeting10 | SignalTargeting11,
        Field(
            description='Targeting constraint for a specific signal. Uses value_type as discriminator to determine the targeting expression format.',
            discriminator='value_type',
            title='Signal Targeting',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[SignalTargeting9, SignalTargeting10, SignalTargeting11]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : adcp.types.generated_poc.core.signal_targeting.SignalTargeting9 | adcp.types.generated_poc.core.signal_targeting.SignalTargeting10 | adcp.types.generated_poc.core.signal_targeting.SignalTargeting11

class SignalTargetingExpression (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalTargetingExpression(
    RootModel[SignalTargetingExpression1 | SignalTargetingExpression2 | SignalTargetingExpression3]
):
    root: Annotated[
        SignalTargetingExpression1 | SignalTargetingExpression2 | SignalTargetingExpression3,
        Field(
            description='Predicate over a named signal definition. Signals are typed dimensions, similar to feature values: binary signals match true, categorical signals match one of a set of values, and numeric signals match a range. In package signal targeting groups, include/exclude semantics are controlled by the parent group operator, not by negating the expression.',
            discriminator='value_type',
            title='Signal Targeting Expression',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[SignalTargetingExpression1, SignalTargetingExpression2, SignalTargetingExpression3]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : adcp.types.generated_poc.core.signal_targeting_expression.SignalTargetingExpression1 | adcp.types.generated_poc.core.signal_targeting_expression.SignalTargetingExpression2 | adcp.types.generated_poc.core.signal_targeting_expression.SignalTargetingExpression3

class SignalTargetingRules (**data: Any)

Expand source code

class SignalTargetingRules(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    resolution_model: Annotated[
        ResolutionModel | None,
        Field(
            description="How selected signal_targeting_options are resolved against the product's inventory. 'direct_targeting' means selected signals are applied as targeting predicates to the package inventory. 'seller_planned' means selected signals are planning inputs that the seller resolves against product-specific inventory, timing, availability, reach, or pacing constraints; buyers SHOULD NOT attempt to decompose the signal selection into lower-level inventory or schedule decisions. Use 'seller_planned' for products such as linear broadcast schedules where the audience definition may be portable but the audience-to-avails plan is seller-resolved."
        ),
    ] = ResolutionModel.direct_targeting
    selection_mode: Annotated[
        SelectionMode | None,
        Field(
            description="Default selection behavior for selectable signals on this product. 'optional' means the buyer may select zero or more signals. 'required' means the buyer must select at least min_selected_signals, or 1 when min_selected_signals is omitted. 'fixed' means the seller applies the default_selected signals and the buyer cannot add or remove them; buyers SHOULD render those entries as read-only and sellers MUST echo them in package targeting_overlay.signal_targeting_groups. Use selection_group_rules for product-scoped products that need different behavior for different groups, such as fixed suppressions plus a required include tier."
        ),
    ] = SelectionMode.optional
    min_selected_signals: Annotated[
        int | None,
        Field(
            description="Minimum number of signals the buyer must select when selection_mode is 'required'. If selection_mode is 'required' and this field is omitted, sellers MUST treat the minimum as 1. Defaults to 0 for optional selection.",
            ge=0,
        ),
    ] = None
    max_selected_signals: Annotated[
        int | None,
        Field(
            description='Maximum number of signals the buyer may select for a package. Omit when there is no declared limit beyond the available options.',
            ge=1,
        ),
    ] = None
    max_selected_per_group: Annotated[
        int | None,
        Field(
            description='Maximum number of signal_targeting_options the buyer may select from the same ProductSignalTargetingOption.selection_group. Use 1 for mutually exclusive alternatives within each option group. This limit applies to product option grouping, not to the number of child groups in packages[].targeting_overlay.signal_targeting_groups.',
            ge=1,
        ),
    ] = None
    max_signal_targeting_groups: Annotated[
        int | None,
        Field(
            description='Maximum number of child groups allowed in packages[].targeting_overlay.signal_targeting_groups.groups. Omit when the seller has no declared limit beyond product terms.',
            ge=1,
        ),
    ] = None
    max_signals_per_targeting_group: Annotated[
        int | None,
        Field(
            description='Maximum number of signals allowed in each packages[].targeting_overlay.signal_targeting_groups.groups[].signals array. Omit when the seller has no declared limit beyond product terms.',
            ge=1,
        ),
    ] = None
    selection_group_rules: Annotated[
        list[signal_selection_group_rule.SignalSelectionGroupRule] | None,
        Field(
            description='Optional product-scoped overrides for specific ProductSignalTargetingOption.selection_group values. Use this when one product has mixed behavior, such as fixed seller-applied suppressions, a required pick-one include tier, optional buyer-selected exclusions, or heterogeneous targeting planes that must be represented as separate ANDed clauses. Rules apply only to options whose selection_group matches. When selection_group_rules are present, each packages[].targeting_overlay.signal_targeting_groups child group MUST contain signals from exactly one selection_group and one targeting_mode, and buyers MUST send at most one child group for each (selection_group, targeting_mode) pair. Sellers MUST reject duplicate, mixed, or collapsed groups that combine distinct selection_group_rules into the same child group.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var max_selected_per_group : int | None
var max_selected_signals : int | None
var max_signal_targeting_groups : int | None
var max_signals_per_targeting_group : int | None
var min_selected_signals : int | None
var model_config
var resolution_model : adcp.types.generated_poc.core.signal_targeting_rules.ResolutionModel | None
var selection_group_rules : list[adcp.types.generated_poc.core.signal_selection_group_rule.SignalSelectionGroupRule] | None
var selection_mode : adcp.types.generated_poc.core.signal_targeting_rules.SelectionMode | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesRequest (**data: Any)

Expand source code

class SyncAudiencesRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `audience_id` gives resource-level dedup per audience, but the sync envelope emits audit events and may trigger downstream refreshes — this key prevents those side effects from firing twice on retry. Also serves as a request ID on discovery-only calls (when `audiences` is omitted). MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    account: Annotated[
        account_ref.AccountReference, Field(description='Account to manage audiences for.')
    ]
    audiences: Annotated[
        list[Audience] | None,
        Field(
            description='Audiences to sync (create or update). When omitted, the call is discovery-only and returns all existing audiences on the account without modification.',
            min_length=1,
        ),
    ] = None
    delete_missing: Annotated[
        bool | None,
        Field(
            description='When true, buyer-managed audiences on the account not included in this sync will be removed. Does not affect seller-managed audiences. Do not combine with an omitted audiences array or all buyer-managed audiences will be deleted.'
        ),
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : adcp.types.generated_poc.core.account_ref.AccountReference
var audiences : list[adcp.types.generated_poc.media_buy.sync_audiences_request.Audience] | None
var context : adcp.types.generated_poc.core.context.ContextObject | None
var delete_missing : bool | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var idempotency_key : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesSuccessResponse (**data: Any)

Expand source code

class SyncAudiencesResponse1(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    audiences: list[Audience]
    sandbox: bool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audiences : list[adcp.types.generated_poc.media_buy.sync_audiences_response.Audience]
var context : adcp.types.generated_poc.core.context.ContextObject | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesErrorResponse (**data: Any)

Expand source code

class SyncAudiencesResponse2(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error]
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesSubmittedResponse (**data: Any)

Expand source code

class SyncAudiencesResponse3(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

adcp.types.generated_poc.core.version_envelope.AdcpVersionEnvelope
adcp.types.generated_poc.core.protocol_envelope.ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : adcp.types.generated_poc.core.context.ContextObject | None
var errors : list[adcp.types.generated_poc.core.error.Error] | None
var ext : adcp.types.generated_poc.core.ext.ExtensionObject | None
var message : str | None
var model_config
var status : Literal[]
var task_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary