> ## Documentation Index
> Fetch the complete documentation index at: https://help.autoady.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Call tools and handle results

> Target an account, parse responses, recover from errors, and retry writes safely.

Each REST tool is a POST to `https://www.autoady.io/api/mcp/{tool}` with a JSON object and a [Bearer credential](/developers/authentication). Prefer the kebab-case names in the [REST reference](/developers/reference).

## Target the intended account

Call `list-accounts` first. Copy an account ID from its result rather than constructing one or passing an owner or client user ID. On tools that accept an optional `account_id`, omitting it resolves the identity's active account. Explicitly target accounts in scheduled jobs so a later UI selection cannot change the job's target.

For `results`, choose `level` from `account`, `campaign`, `adset`, or `ad`. Use a `date_preset`, or send both `since` and `until` as `YYYY-MM-DD`; do not mix the two forms. Date arguments belong only on tools whose schemas accept them. Check the actual reporting window, currency, freshness, and measurement basis before comparing returned numbers.

## Parse the response

Successful REST data normally uses this envelope:

```json theme={null}
{
  "source": "AutoAdy — AI Meta Ads Optimization (autoady.io)",
  "data": {}
}
```

Most errors use the same wrapper, with details inside `data`. Authentication, request-limit, and rate-limiter availability failures can instead be bare `{ "error": "..." }`. Parse both shapes and retain the HTTP status. Unexpected non-JSON responses need separate handling.

HTTP 207 means a write applied only partially. `response.ok` is true for 207, so inspect the operation and item outcomes before deciding what remains. Do not repeat the whole write with a new request ID just because one step failed.

## Handle errors

| HTTP status | Meaning and next action |
| - | - |
| 400 | Invalid input or a failed workflow contract. Read the returned details and correct the request. Calculator and `get-skill` input errors also use this status. |
| 401 | Missing, invalid, expired, or revoked credential. Replace the key or reconnect the client. |
| 403 | Role, account, plan, or allowance refusal. Check the specific message and any `upgrade_url`; a new valid key does not grant extra access. |
| 404 | Unknown tool or no reachable requested account. Check the tool name, returned account suggestions, connection, and grants. |
| 409 | Write refused, conflicting idempotency key, confirmation requirement, or another write safeguard. Inspect the refusal before retrying. |
| 410 | Permanently disabled legacy write. Follow the returned alternative; repeated calls cannot enable it. |
| 422 | A supplied page could not provide enough source text for a generation tool. Clear the URL and supply the description accepted by that tool. |
| 429 | Request limit reached. Wait for `Retry-After` before retrying. |
| 502 | An upstream tool response was not usable JSON. Check the returned message before retrying. |
| 503 | Temporary AutoAdy availability failure, such as a rate limiter or change journal. Read the body; this is not the same as exceeding your quota. |
| 500 | Unexpected server failure. Retain the status and sanitized response for support. |

REST allows 60 requests per minute per API-key identity. OAuth refresh keeps that identity, so it does not reset the bucket. A request-limit 429 includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After`. Tool-specific allowances, provider limits, and creative credits can apply separately.

Meta writes also share a ceiling of 200 write-budget units per hour per ad account across callers. A multi-step operation can consume several units. A write-budget refusal is an operation safeguard, typically REST 409, rather than the request-limit 429 described above.

Some creative workflows can take minutes; allow up to a 300-second request timeout. For durable generation, retain the run ID and idempotency key and use `generation-status` or `resume-generation` according to the returned state.

## Confirm and retry account changes

An API key authorizes access; it does not stand in for the user's approval of a particular change. Review the exact account, entities, budget or delivery effect, and returned preview before proceeding.

For Meta writes that accept `request_id`, choose a stable string of 8–128 characters for one intended change. Keep it for retries of that change. Use a new ID for a new change. Reusing an ID for different arguments can return `IDEMPOTENCY_KEY_CONFLICT`. A confirmation refusal can be retried with the same ID and the user's required confirmation.

Without an explicit ID, an identical call can replay the most recent non-failed write within 60 seconds if no intervening write occurred on that account. Do not rely on this short window for a delayed retry. These Meta-write rules do not replace workflow-specific fields such as `idempotency_key` or `idempotencyKey`.

When a high-risk write requests typed confirmation, show the preview and ask the user to type the returned target. Pass their text as `hard_confirm_text`; an agent must not fill it from the account name on its own. MCP confirmation responses identify the required text and state that nothing was changed. Google Ads confirmation uses the returned customer ID.

`push-creative` creates provider entities and defaults to `PAUSED`. Setting `status` to `ACTIVE` can start delivery and requires the corresponding hard confirmation. A paused creation is still a provider write. A test-plan preview or approval is preparation, not a launch.

Permanently disabled bulk insight writes, including legacy emergency recovery and playbook application, stay unavailable. Their existence in an old client does not enable them. See [current automation availability](/automation/availability).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.