Imports EC sales data into the tenant. Choose one of two payload types via payload_type:

payload_type=csv (default)

Sync a source CSV (e.g. a sales export downloaded from Amazon, Rakuten, or your own EC).

1. Download the sales CSV from the EC mall to a local file.

2. Base64-encode the file's bytes and send it as csv_payload.

3. Map each CSV column header to the five required normalized fields via mapping: product_id, product_name, sold_on, sales_amount, sales_quantity.

payload_type=json

Send the rows directly as records — an array of objects keyed by the canonical field names. No mapping or csv_payload is needed.

For both modes set source_channel (e.g. amazon, rakuten, owned) — it is normalized (lowercased, spaces → dashes).

Notes

• Rows are upserted on the business key (source_channel × product_id × sold_on). Re-sending the same rows updates them in place — the sync is idempotent.

• sold_on must be a complete date (year, month, and day). Accepted formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD.

• sales_amount and sales_quantity must be zero or greater. Currency symbols/commas in amounts are stripped.

• On any row or mapping error nothing is written and a 422 is returned with the per-row messages in error.details.errors.

• After syncing, confirm with read_ec_sync_status. Individual sales rows are never readable back through the API.

Deletes synced EC sales data for a channel. Provide source_channel (required) and optionally imported_on:

• with imported_on → deletes only that import batch (the rows synced on that date).

• without imported_on → deletes the entire channel.

Deletion is idempotent: deleted_count is 0 when nothing matched. Use read_ec_sync_status to discover the channels and import dates available to delete.

Confirms whether EC sales data has been synced. Returns aggregate counts and timestamps per channel plus the most recent sync batches.

For security, this endpoint does not expose individual sales rows or amounts — it is only a confirmation that a sync happened. Use it after import_ec_sales to verify the rows landed.

Returns the tenant's current-month token quota and consumption. Use it to check remaining budget before starting analysis. A pure read — it does not affect runs or workspaces.

Returns the tenant's workspaces. A workspace is a container for saving and reusing analysis conditions, passed as workspace_id to start_run. To just run a new analysis, create one with create_workspace.

Creates a new workspace and returns its id. Pass the returned id as workspace_id to start_run. Analysis conditions themselves are not set here — specify them in the start_run body.

Returns a single workspace by ID. Unknown or other-tenant IDs return 404.

Starts an analysis run in the given workspace. This is the entry point of the workflow. Save data.token from the 202 response, wait for succeeded via read_run_status, then call the result endpoints.

• social_queries: one row per (keyword, source) pair. Repeat rows to search multiple keywords and/or platforms.

• Set product_id / competitor_asins to enable correlation between social metrics and EC sales (read_ec_results owned / competitor). Omit for social-only analysis.

• If a run is already running for the tenant, returns 429 (one concurrent run max). Wait for the prior run to finish.

• Invalid conditions (e.g. a bad date) return 422.

Lists the tenant's past runs, newest first. Use it to find a run whose token you didn't save, or to revisit past analyses. keywords / sources are contains-all filters (a run must include every value given). Page through with meta.next_cursor.

Returns the run's current status. After start_run, poll this until data.status becomes succeeded. On succeeded, the result endpoints (read_result_summary / read_social_results / read_social_accounts / read_ec_results) become available. On failed, data.error holds the failure reason. Always confirm completion here before calling the result endpoints.

Fetches the individual social posts of a completed run, with metrics. Returns 409 if the run is incomplete. Filter by source / keyword / date, and order with sort / direction. Pass cursor until meta.next_cursor is null to fetch everything. Use this for post-level detail (use read_result_summary for the big picture).

Returns the overall summary of a completed run: collected counts, a per-(keyword, source) overview, the social-metric × EC-sales correlation chart, and which EC datasets are available — all at a glance. Best first step when fetching results. Returns 409 if the run is incomplete. Only datasets where data.datasets.owned_ec / competitor_ec is true can be fetched via read_ec_results.

Fetches per-account aggregates of a completed run (follower count, total views, view/follower rate). Returns 409 if the run is incomplete. Use it to see which accounts / influencers are driving results. Filter by source / min_followers, order with sort / direction, and page with cursor.

Fetches daily EC performance of a completed run. Returns 409 if the run is incomplete. dataset=owned is your own performance (when start_run had product_id); dataset=competitor is competitor performance (when competitor_asins was set; one row per ASIN). Check which datasets are available via the datasets field of read_result_summary. A dataset other than owned/competitor returns 422.