Limits & Boundary
Rate limits
Limits apply per account, across all of its API keys.
| Limit | Value | Error when exceeded |
|---|---|---|
| Minimum interval between call starts | 1 second | RATE_LIMITED |
| Concurrent calls | 20 | RATE_LIMITED |
| Calls per day | 10,000, reset at midnight US Eastern time | RATE_LIMITED |
| Service capacity | Shared across all accounts | SHARED_CAPACITY |
Every call that passes parameter validation counts toward the limits, including refused requests and calls that then fail, for example on an image URL, a stale item_id, or INSUFFICIENT_CREDITS. Calls rejected for a malformed parameter do not count.
Rate-limit errors carry details.retry_after_seconds: the time until the next call can start. For the daily limit, that is the time until midnight US Eastern time.
Need higher limits? Email support@commerceai.ai with your use case.
Timeouts
A call usually takes 20 to 40 seconds and can take up to about 2 minutes when the agent searches and compares many products. Set your client timeout to at least 130 seconds. A call that runs longer than that on the server returns UPSTREAM_TIMEOUT.
Lifetimes
| Item | Lifetime |
|---|---|
| API key | Until you delete it. Up to 5 active keys per account. |
conversation_id | 48 hours after the last call, and at most 30 days after the conversation started |
item_id | 48 hours after it was returned, in the conversation it came from |
What the agent covers
| In scope | Out of scope | Result for out-of-scope requests |
|---|---|---|
| US catalog | Other markets | Refused, 0 credits |
| Product search and discovery | Viewing or changing a cart | Refused, 0 credits |
| Comparison of products already shown | Order tracking or placing orders | Refused, 0 credits |
| Product Q&A | Applying coupons or vouchers | Refused, 0 credits |
| Text queries, up to 4,000 characters | Signing in to a store account | Refused, 0 credits |
| Images or image URLs | INVALID_ARGUMENT, not charged |
Out-of-scope requests are recognized from the wording of query. A request that mixes shopping with an out-of-scope action, for example "find a charger and add it to my cart", may be refused as a whole. Send the shopping part on its own.
Data returned
- Prices and availability come from the merchant at the time of the call and can change. Show
purchase_urlso the shopper confirms the final price on the merchant's page. - CommerceAI does not complete purchases. The shopper buys on the merchant's page behind
purchase_url. answer_textis Markdown with inline markers for product cards and comparison tables. See Agent Capabilities.