Amazon-Ads full reference

This connector is optimized for AI agents. For the data replication connector, see Amazon Ads.

This is the full reference documentation for the Amazon-Ads agent connector.

Supported entities and actions

The Amazon-Ads connector supports the following entities and actions.

Entity	Actions
Profiles	List, Get, Context Store Search, Context Store SQL Query
Portfolios	List, Get
Sponsored Product Campaigns	List, Get
Sponsored Product Ad Groups	List
Sponsored Product Keywords	List
Sponsored Product Product Ads	List
Sponsored Product Targets	List
Sponsored Product Negative Keywords	List
Sponsored Product Negative Targets	List
Sponsored Brands Campaigns	List
Sponsored Brands Ad Groups	List

Profiles

Profiles List

Returns a list of advertising profiles associated with the authenticated user. Profiles represent an advertiser's account in a specific marketplace. Advertisers may have a single profile if they advertise in only one marketplace, or a separate profile for each marketplace if they advertise regionally or globally.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "profiles",
  "action": "list"
}'

Python SDK

await amazon_ads.profiles.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profiles",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
profileTypeFilter	string	No	Filter profiles by type. Comma-separated list of profile types.
Valid values: seller, vendor, agency

Response Schema

Records

Field Name	Type	Description
profileId	integer
countryCode	string | null
currencyCode	string | null
dailyBudget	number | null
timezone	string | null
accountInfo	object | any

Profiles Get

Retrieves a single advertising profile by its ID. The profile contains information about the advertiser's account in a specific marketplace.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "profiles",
  "action": "get",
  "params": {
    "profileId": 0
  }
}'

Python SDK

await amazon_ads.profiles.get(
    profile_id=0
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profiles",
    "action": "get",
    "params": {
        "profileId": 0
    }
}'

Parameters

Parameter Name	Type	Required	Description
profileId	integer	Yes	The unique identifier of the profile

Response Schema

Records

Field Name	Type	Description
profileId	integer
countryCode	string | null
currencyCode	string | null
dailyBudget	number | null
timezone	string | null
accountInfo	object | any

Profiles Context Store Search

Search and filter profiles records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "profiles",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "accountInfo": {}
        }
      }
    }
  }
}'

Python SDK

await amazon_ads.profiles.context_store_search(
    query={"filter": {"eq": {"accountInfo": {}}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profiles",
    "action": "context_store_search",
    "params": {
        "query": {"filter": {"eq": {"accountInfo": {}}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
query	object	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, startswith, endswith, contains, array_contains, fuzzy, keyword, not, and, or
query.filter	object	No	Filter conditions
query.sort	array	No	Sort conditions
limit	integer	No	Maximum results to return (default 1000)
cursor	string	No	Pagination cursor from previous response's meta.cursor
fields	array	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
accountInfo	object
countryCode	string
currencyCode	string
dailyBudget	number
profileId	integer
timezone	string

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].accountInfo	object
data[].countryCode	string
data[].currencyCode	string
data[].dailyBudget	number
data[].profileId	integer
data[].timezone	string

Profiles Context Store SQL Query

Run a SQL query against profiles records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "profiles",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await amazon_ads.profiles.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "profiles",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Portfolios

Portfolios List

Returns a list of portfolios for the specified profile. Portfolios are used to group campaigns together for organizational and budget management purposes.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "portfolios",
  "action": "list"
}'

Python SDK

await amazon_ads.portfolios.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "portfolios",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
includeExtendedDataFields	string	No	Whether to include extended data fields in the response

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Portfolios Get

Retrieves a single portfolio by its ID using the v2 API.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "portfolios",
  "action": "get",
  "params": {
    "portfolioId": 0
  }
}'

Python SDK

await amazon_ads.portfolios.get(
    portfolio_id=0
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "portfolios",
    "action": "get",
    "params": {
        "portfolioId": 0
    }
}'

Parameters

Parameter Name	Type	Required	Description
portfolioId	integer	Yes	The unique identifier of the portfolio

Response Schema

Records

Field Name	Type	Description
portfolioId	string | integer
name	string | null
budget	object | any
inBudget	boolean | null
state	string | null
creationDate	integer | null
lastUpdatedDate	integer | null
servingStatus	string | null

Sponsored Product Campaigns

Sponsored Product Campaigns List

Returns a list of sponsored product campaigns for the specified profile. Sponsored Products campaigns promote individual product listings on Amazon.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_campaigns",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_campaigns.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_campaigns",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Campaigns Get

Retrieves a single sponsored product campaign by its ID using the v2 API.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_campaigns",
  "action": "get",
  "params": {
    "campaignId": 0
  }
}'

Python SDK

await amazon_ads.sponsored_product_campaigns.get(
    campaign_id=0
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_campaigns",
    "action": "get",
    "params": {
        "campaignId": 0
    }
}'

Parameters

Parameter Name	Type	Required	Description
campaignId	integer	Yes	The unique identifier of the campaign

Response Schema

Records

Field Name	Type	Description
campaignId	string | integer
portfolioId	string | integer | any
name	string | null
campaignType	string | null
tags	object | null
targetingType	string | null
premiumBidAdjustment	boolean | null
state	string | null
dynamicBidding	object | any
bidding	object | any
startDate	string | null
endDate	string | null
dailyBudget	number | null
budget	object | any
extendedData	object | null
marketplaceBudgetAllocation	string | null
offAmazonSettings	object | null

Sponsored Product Ad Groups

Sponsored Product Ad Groups List

Returns a list of sponsored product ad groups for the specified profile. Ad groups are used to organize ads and targeting within a campaign.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_ad_groups",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_ad_groups.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_ad_groups",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Keywords

Sponsored Product Keywords List

Returns a list of sponsored product keywords for the specified profile. Keywords are used in manual targeting campaigns to match shopper search queries.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_keywords",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_keywords.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_keywords",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Product Ads

Sponsored Product Product Ads List

Returns a list of sponsored product ads for the specified profile. Product ads associate an advertised product with an ad group.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_product_ads",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_product_ads.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_product_ads",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Targets

Sponsored Product Targets List

Returns a list of sponsored product targeting clauses for the specified profile. Targeting clauses define product or category targeting for ad groups.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_targets",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_targets.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_targets",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Negative Keywords

Sponsored Product Negative Keywords List

Returns a list of sponsored product negative keywords for the specified profile. Negative keywords prevent ads from showing for specific search terms.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_negative_keywords",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_negative_keywords.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_negative_keywords",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Product Negative Targets

Sponsored Product Negative Targets List

Returns a list of sponsored product negative targeting clauses for the specified profile. Negative targeting clauses exclude specific products or categories from targeting.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_product_negative_targets",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_product_negative_targets.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_product_negative_targets",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Brands Campaigns

Sponsored Brands Campaigns List

Returns a list of sponsored brands campaigns for the specified profile. Sponsored Brands campaigns help drive discovery and sales with creative ad experiences.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_brands_campaigns",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_brands_campaigns.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_brands_campaigns",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null

Sponsored Brands Ad Groups

Sponsored Brands Ad Groups List

Returns a list of sponsored brands ad groups for the specified profile. Ad groups organize ads and targeting within a Sponsored Brands campaign.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "amazon-ads",
  "entity": "sponsored_brands_ad_groups",
  "action": "list"
}'

Python SDK

await amazon_ads.sponsored_brands_ad_groups.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "sponsored_brands_ad_groups",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
stateFilter	object	No
stateFilter.include	string	No	Comma-separated list of states to include (enabled, paused, archived)
maxResults	integer	No	Maximum number of results to return
nextToken	string	No	Token for pagination

Response Schema

Meta

Field Name	Type	Description
next_token	string | null