Models Reference

Campaigns

asa_api_client.models.Campaign

Bases: BaseModel

An Apple Search Ads campaign.

A campaign is the top-level entity that contains ad groups, keywords, and ads. Each campaign has its own budget and targets specific countries or regions.

Attributes:

Name	Type	Description
id	int	The unique identifier for the campaign.
org_id	int	The organization ID that owns this campaign.
name	str	The campaign name.
budget_amount	Money | None	The total campaign budget.
daily_budget_amount	Money | None	The daily budget limit.
adam_id	int	The App Store app ID being advertised.
countries_or_regions	list[str]	List of targeted country/region codes.
status	CampaignStatus | str	The campaign status (ENABLED/PAUSED).
serving_status	CampaignServingStatus | str	Whether the campaign is currently serving.
serving_state_reasons	list[CampaignServingStateReason | str] | None	Reasons for the current serving state.
modification_time	datetime	When the campaign was last modified.
display_status	CampaignDisplayStatus | str	Human-readable status for display.
supply_sources	list[CampaignSupplySource | str]	Where ads will be shown.
country_or_region_serving_states	list[CountryOrRegionServingState] | None	Per-location serving states.

asa_api_client.models.CampaignCreate

Bases: BaseModel

Request model for creating a new campaign.

Example

Create a search results campaign::

campaign = CampaignCreate(
    name="My App Campaign",
    budget_amount=Money.usd(10000),
    daily_budget_amount=Money.usd(100),
    adam_id=123456789,
    countries_or_regions=["US", "CA", "GB"],
    supply_sources=[CampaignSupplySource.APPSTORE_SEARCH_RESULTS],
)

created = client.campaigns.create(campaign)

asa_api_client.models.CampaignUpdate

Bases: BaseModel

Request model for updating an existing campaign.

Only include the fields you want to update. Fields set to None will not be modified.

Example

Update campaign budget::

update = CampaignUpdate(
    daily_budget_amount=Money.usd(200),
)

updated = client.campaigns.update(campaign_id=123, data=update)

Ad Groups

asa_api_client.models.AdGroup

Bases: BaseModel

An Apple Search Ads ad group.

Ad groups belong to campaigns and contain keywords, targeting criteria, and ads. Each ad group has its own bid settings and targeting dimensions.

Attributes:

Name	Type	Description
id	int	The unique identifier for the ad group.
campaign_id	int	The parent campaign ID.
org_id	int	The organization ID.
name	str	The ad group name.
default_bid_amount	Money	The default bid for keywords.
cpa_goal	CpaGoal | None	Cost per acquisition goal.
automated_keywords_opt_in	AutomatedKeywordsOptInStatus | str | bool	Whether Search Match is enabled.
status	AdGroupStatus | str	The ad group status.
serving_status	AdGroupServingStatus | str	Whether the ad group is serving.
serving_state_reasons	list[AdGroupServingStateReason | str] | None	Reasons for current serving state.
display_status	AdGroupDisplayStatus | str	Human-readable status.
targeting_dimensions	TargetingDimensions | None	Audience targeting settings.
modification_time	datetime	When the ad group was last modified.
pricing_model	PricingModel | str | None	The bid pricing model (CPC or CPM).

asa_api_client.models.AdGroupCreate

Bases: BaseModel

Request model for creating a new ad group.

Example

Create an ad group with targeting::

ad_group = AdGroupCreate(
    name="US iPhone Users",
    default_bid_amount=Money.usd("1.50"),
    targeting_dimensions=TargetingDimensions(
        device_class=TargetingDimensionValue(
            included=[DeviceClass.IPHONE]
        ),
    ),
)

created = client.campaigns(123).ad_groups.create(ad_group)

serialize_datetime(value)

Serialize datetime to ISO 8601 format for API.

Keywords

asa_api_client.models.Keyword

Bases: BaseModel

A targeting keyword for bidding.

Targeting keywords are the search terms you bid on to show your ads. Each keyword can have a custom bid amount.

Attributes:

Name	Type	Description
id	int	The unique identifier for the keyword.
campaign_id	int	The parent campaign ID.
ad_group_id	int	The parent ad group ID.
text	str	The keyword text.
match_type	KeywordMatchType | str	How strictly to match search queries.
status	KeywordStatus | str	The keyword status.
bid_amount	Money	The bid amount for this keyword.
modification_time	datetime	When the keyword was last modified.
deleted	bool	Whether the keyword has been deleted.

asa_api_client.models.KeywordCreate

Bases: BaseModel

Request model for creating a targeting keyword.

Example

Create an exact match keyword::

keyword = KeywordCreate(
    text="productivity app",
    match_type=KeywordMatchType.EXACT,
    bid_amount=Money.usd("2.50"),
)

created = client.campaigns(123).ad_groups(456).keywords.create(keyword)

Bulk create keywords::

keywords = [
    KeywordCreate(text="task manager", match_type=KeywordMatchType.BROAD),
    KeywordCreate(text="todo app", match_type=KeywordMatchType.EXACT),
]

created = client.campaigns(123).ad_groups(456).keywords.create_bulk(keywords)

Common

asa_api_client.models.Money

Bases: BaseModel

Represents a monetary amount with currency.

Attributes:

Name	Type	Description
amount	str	The monetary amount as a string to preserve precision.
currency	str	The ISO 4217 currency code (e.g., "USD", "EUR").

usd(amount) classmethod

Create a Money instance in USD.

Parameters:

Name	Type	Description	Default
amount	float | int | str	The amount in USD.	required

Returns:

Type	Description
Self	A Money instance with USD currency.

asa_api_client.models.Selector

Bases: BaseModel

A query selector for filtering and sorting results.

Selectors provide a fluent interface for building complex queries with conditions, sorting, and pagination.

Example

Build a selector with conditions::

selector = (
    Selector()
    .where("status", "==", "ENABLED")
    .where("budgetAmount.amount", ">", "100")
    .order_by("modificationTime", descending=True)
    .limit(50)
)

campaigns = client.campaigns.find(selector)

limit(count)

Set the maximum number of results.

Parameters:

Name	Type	Description	Default
count	int	The maximum number of results to return.	required

Returns:

Type	Description
Self	Self for method chaining.

offset(start)

Set the starting position for results.

Parameters:

Name	Type	Description	Default
start	int	The starting position (0-indexed).	required

Returns:

Type	Description
Self	Self for method chaining.

select(*fields)

Specify which fields to return.

Parameters:

Name	Type	Description	Default
*fields	str	The field names to include in the response.	()

Returns:

Type	Description
Self	Self for method chaining.

sort_by(field, *, descending=False)

Add a sort specification.

Parameters:

Name	Type	Description	Default
field	str	The field to sort by.	required
descending	bool	If True, sort in descending order.	False

Returns:

Type	Description
Self	Self for method chaining.

where(field, operator, values)

Add a filter condition.

Parameters:

Name	Type	Description	Default
field	str	The field to filter on.	required
operator	str | ConditionOperator	The comparison operator. Can be a Python operator string ("==", "!=", "<", etc.) or a ConditionOperator.	required
values	str | list[str]	The value(s) to compare against.	required

Returns:

Type	Description
Self	Self for method chaining.

Example

Filter enabled campaigns with budget > 100::

selector = (
    Selector()
    .where("status", "==", "ENABLED")
    .where("budgetAmount.amount", ">", "100")
)