UTM Builder API

Apply one UTM parameter set to one or many landing page URLs. Quota is counted by successfully built links.

Authentication

Create an API key from settings. The full secret is shown once, so copy it into your agent or secret manager. Later views only show a masked key.

Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...

Quota And Rate Limits

API usage is tracked separately. Responses include quota and rate-limit headers so your agent can decide whether to continue.

X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30

Safe Retries

If a request times out or your agent retries automatically, send the same Idempotency-Key. The same request key and body reuse the result without duplicate generation or quota usage.

Idempotency-Key: order-sync-2026-06-14-001

Current Plan Limits

Limits are calculated from the current membership tier of the API key owner. Send requests sequentially; the quota and rateLimit fields in each response are the source of truth for your agent.

Plan	API access	Daily quota	Per request	Per minute	How to use it
Basic	Not included in API access today	Unavailable	Unavailable	Unavailable	If the API returns membership_required, stop and check the account plan.
Pro	Included	1,000 links	Up to 100 links	30 requests	urls is the batch link list. Building 10 successful links consumes 10 link units. Stop or split the request when quota.remaining is lower than the link count.
Max	Included	10,000 links	Up to 500 links	120 requests	urls is the batch link list. Building 10 successful links consumes 10 link units. Stop or split the request when quota.remaining is lower than the link count.

Send Requests Sequentially

For the same API key and tool, Ecomwith handles one request at a time. If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.

Copy This To Your Agent

Give this instruction to your automation agent so it knows how to authenticate, request, handle quota, rate limits, and safe retries.

You are my automation agent. Use the Ecomwith Tool API to call the UTM Builder API, and never print the full API key.

Authentication:
- Read ECOMWITH_API_KEY from the environment.
- Send Authorization: Bearer <ECOMWITH_API_KEY>.

Request:
- Endpoint: POST https://ecomwith.com/api/v1/tools/utm-builder/build
- Body example: {"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience"}
- Building 10 successful links consumes 10 link units. URLs returned in invalid do not consume quota.

Current limits:
- Pro: 1,000 links per day, up to 100 links per request, up to 30 requests per minute.
- Max: 10,000 links per day, up to 500 links per request, up to 120 requests per minute.

Rules:
- Send requests sequentially. Do not call the same tool concurrently.
- Use one stable Idempotency-Key per business batch, for example utm-campaign-2026-06-17-batch-1.
- Handle concurrency_limited, rate_limited, quota_exceeded, and idempotency_conflict by stopping or retrying according to the code.

On success, return links, invalid, quota.remaining, and rateLimit.remaining.

Example Requests

curl -X POST https://ecomwith.com/api/v1/tools/utm-builder/build \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: utm-batch-001" \
  -d '{"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience"}'