Skip to main content
DataDoe HubHub
(opens in a new tab)
ChatGPT (opens in a new tab)
Claude (opens in a new tab)

What is Amazon Marketing Cloud in DataDoe?

Amazon Marketing Cloud (AMC) lets AI agents and integrations run SQL against the AMC instance of a Seller or Vendor, through DataDoe MCP or the REST API. You can start from ready-made query templates or write your own SQL, save workflows with optional schedules, start on-demand queries, poll for results, and download Amazon result files.

AMC is in beta and available to every organization. You do not need to request access: enable AMC for a Seller or Vendor as described below.

How do I enable AMC?

  1. Connect Amazon Ads for the Seller or Vendor on the same marketplace (see below for the supported AMC access paths).
  2. On the Accounts page (opens in a new tab), click AMC in the account's row (or Manage AMC in the account details). It opens the account's Amazon Marketing Cloud page. Click Enable AMC. Only the organization owner can enable or change AMC. For self-service AMC, DataDoe asks you to confirm first, because enabling creates the AMC instance in your Amazon Ads account if it does not exist yet.
  3. Enable starts setup in the background. We email organization owners when AMC is ready (unless they turned off this email); you do not need to wait in DataDoe. Queries and workflows then run through MCP or the REST API. Until AMC is enabled for a Seller or Vendor, AMC tools and routes for it return HTTP 404 AMC_NOT_FOUND with a message saying AMC is not connected.
  4. To validate, start, or cancel queries and to create, update, or delete workflows, set the Seller or Vendor's Access level to Read and write on the Accounts page (opens in a new tab). With the default Read only access, you can read the schema, workflows, and results, but those operations return HTTP 403 AMC_FORBIDDEN.

Which Amazon AMC accounts does DataDoe support?

Amazon has several AMC access paths. See Amazon's AMC overview (opens in a new tab):

  • AMC accounts that can create new instances through the Amazon Ads API (usually provisioned by Amazon after a request through an Amazon Ads account executive or partner): DataDoe creates a dedicated instance in that AMC account.
  • Self-service AMC for Sponsored Ads advertisers: one standard instance per Sponsored Ads account and marketplace, also used by AMC in the Amazon Ads console. DataDoe connects that instance when the Ads connection has no AMC account for the marketplace.

DataDoe picks the path automatically: if the Ads connection has an AMC account on the marketplace, it uses that account (if there are several, the organization owner picks one); otherwise it offers self-service AMC. DataDoe does not support agency or manager accounts.

What to know about self-service AMC:

  • Amazon requires the Amazon login used for the Ads connection to accept the AMC terms once per region (North America, Europe, Far East) in the Amazon Marketing Cloud console (opens in a new tab). Until then, DataDoe shows AMC terms required. After you accept the terms, DataDoe usually resumes setup automatically within a few minutes; use Restore access to retry right away.
  • The instance is shared with the AMC console: workflows and results created there are also visible through DataDoe, and deleting a workflow through DataDoe deletes it in the console too.
  • Amazon does not allow deleting self-service instances through the API. Disconnecting AMC in DataDoe only removes the DataDoe connection; the instance, its workflows, and schedules stay in your Amazon Ads account.

If the account is ineligible after Ads is connected, use the contact form (opens in a new tab).

How do I disconnect AMC?

  1. On the Accounts page (opens in a new tab), click AMC in the account's row. Only the organization owner can disconnect AMC.
  2. Click Disconnect AMC and confirm. While DataDoe is creating a dedicated instance (status Creating instance), wait until that step finishes.
  3. Disconnecting runs in the background. The status shows Disconnecting until it finishes.

You must disconnect AMC before you delete a Seller, Vendor, or Amazon Ads only account, or change its Ads connection. Until then, the delete button in the account's row on the Accounts page is disabled.

Disconnecting a dedicated instance (created by DataDoe in an AMC account) deletes it: DataDoe cancels running queries and deletes the instance's workflows, schedules, and the instance itself. Disconnecting self-service AMC only removes the DataDoe connection; the instance stays in your Amazon Ads account. After any disconnect, past results are no longer available through DataDoe.

How much does it cost?

AMC itself is free for advertisers. Retrieving an AMC query result through DataDoe costs 5 AI Tokens (list price), charged once per execution the first time its files are returned. It is currently promotional at 0 AI Tokens. Starting and validating queries, failed and cancelled executions, and fetching the same result again are free. See Subscription and pricing.

If your AI Token balance runs out, Amazon keeps running your workflows and schedules (DataDoe never pauses them). Retrieving a result that has not been charged yet returns the no-tokens error (HTTP 402, the same error other paid operations return) until you refill your balance. Results stay available until their expiresAt, so refill before then. Results that were already retrieved and charged can be fetched again for free. Starting a query is free and never checks your balance.

What limits does Amazon apply?

Use on-demand queries for testing and one-off reports. For recurring reports, save the SQL as a workflow with a schedule.

  • 30 on-demand executions per day per instance. Every on-demand start counts, with sql and with workflowId alike; only scheduled runs are exempt. Validation (dry run) does not count. Amazon does not document when the day resets. Over the limit, starting a query fails with HTTP 429 AMC_AD_HOC_LIMIT_REACHED; retry later.
  • 10 executions running in parallel per instance. Further executions wait in Amazon's queue. A self-service instance shares this with runs started in the AMC console.

Amazon may change these limits. See Amazon's workflow execution guide (opens in a new tab).

How to run an AMC query?

Runtime depends on the query. Amazon documents that executions typically take at least 15 minutes; simple COUNT/aggregations can finish in under a minute — treat this as a range, not a guarantee. Poll no faster than 5 seconds. Cancel while delivery is WAITING if you do not want to wait; once AVAILABLE the result stays. Download URLs last about 10 minutes — download immediately when they appear.

Provide exactly one of sql, workflowId, or templateId. Raw ad-hoc SQL is never persisted. Reuse requestId only with an identical payload.

For an EXPLICIT time window, timeWindowStart and timeWindowEnd are UTC instants (ending in Z), also when you set timeWindowTimeZone.

When validation returns valid: false, each entry in diagnostics has code, severity, and message; the message carries Amazon's error text, for example the line and column and the column or table that was not found. Validation waits up to 15 seconds for Amazon; if it returns AMC_UPSTREAM_UNAVAILABLE, retry with the same requestId.

Query templates

DataDoe maintains ready-made AMC query templates, such as new-to-brand customers by ASIN, keyword halo sales, ad product overlap, path to conversion, cross-sell, and customer value. Start with a template before writing SQL: run it by templateId, or copy its SQL, edit it, and send it as sql. Templates are free; result pricing is the same as for your own SQL.

Some templates need an Amazon paid feature (Amazon Insights). Checking a template with your sellerOrVendorId shows whether the AMC instance has every data source it needs. A template whose data sources are missing is rejected with HTTP 422 AMC_TEMPLATE_DATA_SOURCES_UNAVAILABLE before anything runs in Amazon.

Using MCP

  1. Connect DataDoe to Claude, ChatGPT, or another MCP-capable agent.
  2. Find a template with amc_query_templates_find and read it with amc_query_template_get (pass sellerOrVendorId to check availability). For custom SQL, read the live schema with amc_schema_find.
  3. Dry-run the query with amc_query_validate (exactly one of sql, workflowId, or templateId).
  4. Start the query with amc_query_start.
  5. If the response outcome is OPERATION, poll amc_operation_get until the operation is terminal; when it SUCCEEDED, its resourceId is the resultId. If recoveryStatus is AWAITING_CLIENT_PAYLOAD, resubmit the identical payload and requestId — do not start a second execution.
  6. Poll amc_query_result_get until deliveryStatus is AVAILABLE, then download the files immediately.
  7. Cancel a pending or running query with amc_query_cancel when needed.

You can also list past results with amc_query_results_find. Results of schedules and AMC console runs appear within an hour. Listing results for a specific Seller or Vendor (sellerOrVendorId) first imports its recent Amazon runs, at most every 5 minutes.

Saved SQL lives in workflows (amc_workflows_find / amc_workflows_create / amc_workflows_update / amc_workflows_delete). To schedule a template, call amc_workflows_create with templateId instead of sql; the template's current SQL is copied into the workflow, and amc_workflows_find shows which template and version a workflow uses. Create, update, and delete return accepted operation state — poll amc_operation_get. Updates and deletes require the latest expectedStateHash from amc_workflows_find.

Using API

The easiest way to run AMC with the API is to paste this page URL into your coding AI agent and ask it to generate the code for you.

Authenticate every REST request with the datadoe-api-key header. Do not use X-Api-Key or Authorization.

http
1POST /api/v1/amc/query-executions
2Content-Type: application/json
3datadoe-api-key: YOUR_API_KEY
  1. Set up your DataDoe API connection.
  2. Find a template with GET /amc/query-templates and read it with GET /amc/query-templates/:templateId (add sellerOrVendorId to check availability). For custom SQL, read the live schema with GET /amc/schema.
  3. Dry-run with POST /amc/query-validations (exactly one of sql, workflowId, or templateId).
  4. Start the query with POST /amc/query-executions.
  5. If outcome is OPERATION (HTTP 202), poll GET /amc/operations/:operationId until the operation is terminal; when it SUCCEEDED, its resourceId is the resultId. If recoveryStatus is AWAITING_CLIENT_PAYLOAD, resubmit the identical payload and requestId.
  6. Poll GET /amc/query-results/:resultId until deliveryStatus is AVAILABLE, then download immediately.
  7. Cancel with POST /amc/query-results/:resultId/cancellation when needed.

List past results with GET /amc/query-results (filter template runs with templateId). Workflows: GET|POST /amc/workflows (POST accepts templateId instead of sql), PATCH /amc/workflows/:workflowId, POST /amc/workflows/:workflowId/deletion.

Every write request (validate, start, cancel, and workflow create, update, delete) needs a requestId (UUID) and a sellerOrVendorId in the JSON body. GET /amc/query-results/:resultId and GET /amc/operations/:operationId need sellerOrVendorId as a query parameter. See the DataDoe API docs (opens in a new tab) for request and response schemas.

What errors can AMC return?

AMC errors share one JSON shape: status, entityType (AMC), code, message, retryable, requiredAction, and config. The most common codes:

  • AMC_INVALID_REQUEST (400): the request does not match the schema, for example both sql and workflowId.
  • AMC_TEMPLATE_DATA_SOURCES_UNAVAILABLE (422): the AMC instance lacks a data source the template needs, usually an Amazon paid feature; config lists the missing data sources and paid features. Validation reports the same code as a diagnostic.
  • AMC_FEATURE_DISABLED (403): AMC is turned off for the organization.
  • AMC_FORBIDDEN (403): the Seller or Vendor needs Read and write access for this operation.
  • AMC_NOT_FOUND (404): the Seller or Vendor has no AMC connection, or the result, operation, or workflow does not exist. When AMC is not connected, the message says so and explains how the organization owner enables AMC in DataDoe.
  • AMC_IDEMPOTENCY_CONFLICT (409): a requestId was reused with a different payload.
  • AMC_AD_HOC_LIMIT_REACHED and AMC_UPSTREAM_RATE_LIMITED (429), AMC_UPSTREAM_UNAVAILABLE (503): Amazon limits or outages. They are retryable; REST responses carry a Retry-After header.

Running out of AI Tokens returns the shared no-tokens error (HTTP 402).

What do execution and delivery statuses mean?

Each result has two independent statuses:

  • executionStatus: Amazon query progress — PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.
  • deliveryStatus: whether result files are ready — WAITING, AVAILABLE, FAILED, EXPIRED, CANCELLED.

rowCount may be null until Amazon reports it.

When executionStatus is FAILED, failureReason explains why, for example the SQL error Amazon reported. Each result also includes amazonExecutionId, the execution id shown in the AMC console, which you can use as a filter when listing results.

Cancelling a query whose delivery is still WAITING sets deliveryStatus to CANCELLED. If files are already AVAILABLE, delivery is left unchanged. Cancelling a SUCCEEDED or FAILED result returns AMC_INVALID_REQUEST. Cancel is idempotent after a successful cancel.

Empty privacy-threshold results are ordinary result files.

What should I know about workflow ids?

Workflows that already exist in your AMC instance, including ones created in the AMC console, keep their Amazon ids: letters (including uppercase), digits, ., - and _, up to 128 characters. You can list, validate, start, update and delete them by that id.

Workflows you create through DataDoe, and new schedules, must use ids that match AMC_SLUG_PATTERN: lowercase alphanumeric characters and - only, 1–64 characters, not starting or ending with -. Existing schedule ids can be kept in updates.

Some workflows created with AMC console tools are stored by Amazon without SQL text. They are listed with sql: null; you can run and delete them and change their schedules, but you cannot replace their definition with SQL through DataDoe.

amc_workflows_find / GET /amc/workflows omit ids outside Amazon's format. meta.skippedCount is how many rows were omitted from data.