Exa Cross-layer Troubleshooting

Overview

Localize complex Exa failures across query planning, retrieval, crawling, synthesis, SDK mapping, queues, and downstream consumption. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Search relevance, Contents crawl status, deep output grounding, Agent terminal state, webhook delivery, and application rendering are independent layers. A single request can succeed at one layer and fail at another, so evidence must preserve layer-specific IDs and decisions.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Reproduce with a sanitized input and freeze endpoint, SDK, flags, and time window.
2. Trace the application request through adapter, Exa request ID, results, statuses, and downstream IDs.
3. Separate relevance, freshness, crawl, synthesis, schema, queue, and rendering symptoms.
4. Compare one controlled parameter at a time against a known-good fixture or request.
5. Escalate vendor defects with request IDs, tags, timestamps, and redacted shape evidence.
6. Verify the fix at the failed layer and then end to end before closing.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Changing query, search type, freshness, and content mode together destroys causal evi…

Exa Product Architecture Selection

Overview

Choose among direct Search, staged Contents, Answer, Agent, Monitors, Websets, and Batch using explicit latency, verification, volume, and lifecycle criteria. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

The Exa products are complementary rather than drop-in tiers. Search and Contents suit bounded synchronous retrieval; Answer synthesizes a cited response; Agent performs asynchronous multi-step research; Monitors recur and notify; Websets verify and enrich sets; enabled Batch handles offline Search or Agent volume.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. State the output, verification need, cadence, latency, volume, and cost ceiling.
2. Select the narrowest product and document why simpler options fail.
3. Model synchronous and asynchronous state, callbacks, polling, and terminal outcomes.
4. Place credentials, policy, content inspection, and citations at explicit boundaries.
5. Prototype with synthetic inputs and measure quality, latency, and cost.
6. Record the chosen variant, rejected alternatives, migration triggers, and rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• A more autonomous product is not automatically a better ret…

Exa CI Contract Verification

Overview

Add deterministic Exa contract checks to CI while keeping live credentials, spend, and volatile web results out of ordinary pull requests. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Offline CI can verify owned request and response schemas, error tags, webhook signatures, and redaction. A live lane should be protected, synthetic, manually or schedule authorized, tightly budgeted, and non-blocking until its reliability is understood.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Map the Exa adapter and enumerate contracts changed by the pull request.
2. Add sanitized fixtures for success, partial Contents status, 429, 402, and 503.
3. Verify no load-time shell commands or secret-dependent preprocessing occurs.
4. Test webhook signature verification with fixed local payloads and clocks.
5. Place a one-request live smoke lane behind protected credentials and concurrency.
6. Publish content-free gate evidence and distinguish skipped from passed live checks.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• A skipped live job must not be reported as vendor validation.
• Snapshotting web ranks or text makes pull requests nondeterministic.
• Fork…

Exa Error and Status Decision Tree

Overview

Classify Exa failures by HTTP status, error tag, endpoint, and per-item crawl status before deciding whether to repair, retry, or escalate. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Documented errors distinguish invalid requests, authentication, exhausted credits or budgets, access policy, per-URL crawl failure, rate limiting, service overload, and Answer generation failure. Most errors include requestId, error, and tag; 429 can use a simpler body. Contents also reports granular statuses inside a successful response.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Capture endpoint, status, tag, request ID, attempt, and content-free input shape.
2. Separate request defects from auth, billing, policy, crawl, and capacity classes.
3. Repair 400-class contract errors instead of retrying them unchanged.
4. Honor Retry-After for 429 and use bounded jitter for documented transient failures.
5. Inspect Contents statuses even when the outer request succeeded.
6. Escalate persistent vendor failures with request IDs and redacted timing evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• A 402 is a credit or budget boundary, not a transient server err…

Exa Search and Contents Retrieval Workflow

Overview

Operate Search and Contents as an explicit two-stage retrieval workflow with bounded context, freshness, and cost. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

POST /search can return ranked results and nested contents. POST /contents retrieves known URLs or document IDs and always requires inspection of per-URL statuses. Highlights are token-efficient; text supports deeper analysis; summary is generated. Omitting maxAgeHours uses cache with livecrawl fallback, zero forces livecrawl, and minus one is cache-only.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Classify the query, allowed domains, moderation need, and freshness requirement.
2. Choose type auto unless a measured latency or deep-synthesis need justifies another type.
3. Search with a bounded result count and minimal content mode.
4. Promote only approved URLs or IDs into a Contents request when more context is needed.
5. Inspect every Contents status and quarantine partial crawl failures.
6. Record request IDs, counts, freshness policy, and cost without copied content.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Legacy neural is not the recommended type for new code.
…

Exa Agent Run Lifecycle

Overview

Run asynchronous Exa Agent research with a bounded schema, effort, terminal-state policy, citations, and cleanup decision. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Agent runs are asynchronous unless streamed. A created run returns an ID that must be polled, streamed, stopped, cancelled, or deleted through the Agent lifecycle. Fixed effort provides a predictable price; auto and beta max are usage-metered. Structured output and grounding require separate validation.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Translate the approved research question into a narrow query and optional system prompt.
2. Choose fixed effort or an explicit metered cap and define the output schema.
3. Create one run and persist its content-free run ID.
4. Poll or consume server-sent events with a deadline and terminal-state handling.
5. Validate structured fields, grounding, citations, and cost independently.
6. Stop, cancel, retain, or delete the run according to the approved evidence policy.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Run creation is not completion.
• A schema-valid result can still be weakly grounded or out of scope.
• Cancel, stop, and de…

Exa Cost and Credit Control

Overview

Control Exa spend through endpoint selection, bounded result and content work, per-key budgets, and response-derived cost evidence. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa uses prepaid pay-as-you-go credits unless an enterprise contract says otherwise. Search, Contents, Answer, Monitors, and Agent have different pricing; additional results, summaries, deep types, provider calls, and metered Agent effort can add cost. Higher credit balance does not raise rate limits.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Name the budget owner, team, workload, endpoint mix, and forecast horizon.
2. Verify current first-party pricing or the signed enterprise schedule.
3. Cap results, content types, subpages, freshness, Agent effort, and retry attempts.
4. Use key-level budgets where enabled and independent application-side circuit breakers.
5. Reconcile response costDollars and dashboard billing against workload identifiers.
6. Alert before credit exhaustion and review auto-recharge with its monthly maximum.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not hard-code current public prices as permanent business logic.
• A 402 may mean account cr…

Exa Retrieved-content Governance

Overview

Govern queries, public-web retrieval, generated summaries, citations, and downstream copies across their full retention lifecycle. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Search and Contents can return page text, highlights, summaries, links, images, and subpages; Agent and Answer can generate cited output. Public availability does not remove privacy, copyright, contractual, prompt-injection, or retention obligations. Enterprise Zero Data Retention and request-scoped HIPAA behavior require explicit enablement.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Classify query intent, target domains, returned content, generated output, and citations.
2. Request the smallest content mode and character budget that supports the task.
3. Apply domain, moderation, malware, prompt-injection, and personal-data controls.
4. Keep source attribution and generated claims distinguishable downstream.
5. Define cache, vector-store, log, backup, and deletion propagation before persistence.
6. Verify downstream deletion and preserve only content-free operational receipts.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Highlights are source excerpts; summaries are g…

Exa Privacy-safe Debug Bundle

Overview

Produce a minimal Exa diagnostic bundle that preserves reproducibility without exposing credentials, queries, retrieved content, or customer data. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Useful Exa evidence includes endpoint family, SDK version, request ID, status, error tag, timing, result and status counts, cost, freshness mode, and retry history. Sensitive values and web content are unnecessary for most first-line diagnosis.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Set the incident window, environment, data classification, and evidence owner.
2. Collect configuration names and hashes rather than secret values.
3. Record request IDs, statuses, tags, timing, counts, and retry decisions.
4. Replace queries, URLs, prompts, schemas, and content with approved fingerprints or categories.
5. Scan the candidate bundle for keys, bearer headers, presigned URLs, and customer text.
6. Encrypt, time-bound, and delete the bundle according to the incident policy.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Environment dumps commonly expose EXA_API_KEY and unrelated secrets.
• Returned highlights, summaries, and Agent output may contain sensiti…

Exa Reversible Deployment Workflow

Overview

Deploy an Exa integration with server-side credentials, bounded concurrency, canary controls, and explicit rollback of scheduled work. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Production workers should call Exa from trusted server runtimes. Search and Contents can be synchronous, while Agent, Monitors, Websets, and Batch require durable IDs and terminal-state reconciliation. Deployments must account for queues and scheduled resources that outlive a process release.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Identify every runtime, queue, webhook, schedule, key, and Exa product in the release.
2. Inject environment-specific secrets and deny them to browser or preview builds.
3. Configure timeouts, endpoint budgets, queue bounds, and content-size limits.
4. Deploy dark, validate configuration, then enable a small synthetic canary.
5. Observe request IDs, error classes, latency, cost, and asynchronous backlog.
6. Rollback code and separately pause or reconcile monitors, batches, and runs.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Rolling back code does not cancel vendor-side asynchronous work.
• Preview environments can leak prod…

Exa Team and Enterprise Access Governance

Overview

Govern Exa membership, API and service keys, team budgets, MCP OAuth, and enterprise managed authorization through least privilege and revocation evidence. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa teams own usage and plan features; team admins invite members. Team Management is separately enabled and uses service keys to manage API keys. Enterprise managed authorization for Claude follows Okta directory state for eligible organizations, uses auth.exa.ai and mcp.exa.ai/mcp with scope mcp:tools, and does not create users.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Inventory organization, teams, admins, members, keys, OAuth clients, and workloads.
2. Map each human and service identity to an accountable owner and required surface.
3. Separate administrative service keys from ordinary runtime keys.
4. Apply key budgets and rate limits where the enabled API supports them.
5. Test member removal, key revocation, directory deprovisioning, and MCP session termination.
6. Review access, orphaned schedules, spend, and exceptions on a fixed cadence.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• A team membership model is not a claim of f…

Exa Search Smoke Test

Overview

Prove a new Exa Search integration with a bounded synthetic query and content-free assertions. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

POST /search requires a query and defaults to type auto. New code should not select legacy neural terminology. A successful smoke test checks requestId, bounded results, valid HTTP(S) URLs, and costDollars rather than snapshotting volatile rankings or page text.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Define a non-sensitive query with a stable topical expectation.
2. Set an explicit result cap and omit content extraction for the first probe.
3. Submit one authorized request through the application adapter.
4. Validate requestId, result count, URL schemes, and the cost field.
5. Repeat only once when the failure is explicitly retryable.
6. Delete transient output and retain only content-free evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• HTTP 200 does not prove relevance or freshness.
• Exact rank and title snapshots are brittle because the web index changes.
• A live smoke test without an approved budget is not an offline validation.

Output

Return the operation scope, enviro…

Exa Incident Containment Runbook

Overview

Contain Exa credential, data, cost, capacity, or correctness incidents while preserving safe evidence and vendor request IDs. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Containment choices differ by incident: revoke or rotate a key, disable a caller, pause or delete Monitors, stop or cancel Agent runs, cancel Batches, quarantine webhook processing, or switch to a tested fallback. Deletion and cancellation are destructive and require exact targets.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Declare severity, affected product, environment, owner, and evidence boundary.
2. Stop new work at the narrowest reversible application or queue control.
3. Snapshot content-free IDs, states, costs, error tags, timestamps, and request IDs.
4. Rotate credentials or pause vendor resources only with exact authorization.
5. Reconcile in-flight runs, batches, monitors, webhooks, and downstream outputs.
6. Verify recovery, document residual risk, and time-bound evidence retention.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Blind retries can amplify cost, rate limits, or incorrect output.
• Deleting resources before capturing IDs can destroy the recover…

Exa Authentication and Installation Boundary

Overview

Configure an Exa client without leaking credentials or mixing API-key, MCP OAuth, enterprise managed authorization, and payment-protocol trust models. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

The public REST API uses the Exa API host and an Authorization Bearer header. SDKs can read EXA_API_KEY. Team Management uses a separately enabled service key against the admin API; hosted MCP normally uses OAuth, while enterprise managed authorization currently requires an eligible Exa organization, Claude organization, and Okta setup.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Inventory the runtime, endpoint family, team, environment, and data class.
2. Choose exactly one supported authentication model for that boundary.
3. Place the credential in the approved secret manager and inject it only at runtime.
4. Pin the current SDK or raw-HTTP contract and validate configuration offline.
5. Run a synthetic read-only smoke check only when live access and spend are approved.
6. Record credential owner, scope, rotation path, test result, and rollback state.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not send REST keys in URLs, browser bun…

Exa Integration Pitfall Review

Overview

Audit an Exa integration for stale search types, unsafe secrets, ignored partial failures, unbounded content work, weak citations, and orphaned asynchronous resources. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Common current hazards include legacy neural type usage, stale x-api-key examples instead of Bearer auth, unchecked Contents statuses, forced livecrawl everywhere, unbounded summaries or subpages, unsigned Monitor webhooks, and assumptions that code rollback cancels vendor-side work.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Search code and configuration for every Exa endpoint, SDK call, header, and key.
2. Flag legacy types, stale auth, hidden defaults, beta features, and unbounded parameters.
3. Trace partial statuses, error tags, request IDs, citations, costs, and redaction.
4. Inventory Agent runs, Monitors, Websets, Batches, webhooks, and teardown ownership.
5. Prioritize findings by credential, data, cost, correctness, and availability impact.
6. Repair one bounded contract at a time and add a regression assertion.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not replace a stale literal without validating surrounding behavior…

Exa Load and Capacity Verification

Overview

Validate Exa capacity with synthetic workload models, endpoint-specific budgets, bounded queues, and stop conditions. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Published QPS differs by endpoint and enterprise limits can differ by team. Search, Contents, and Answer have distinct ceilings; asynchronous Agent or Batch is not equivalent to synchronous load. Enterprise Batch is beta, must be enabled, and requires the current first-party Exa-Beta header documented for that feature.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Obtain vendor and service-owner approval for the environment, volume, duration, and spend.
2. Model endpoint mix, result sizes, content modes, freshness, and asynchronous work.
3. Use synthetic non-sensitive inputs and shared limiters across workers.
4. Ramp gradually with hard stop conditions for errors, latency, cost, and backlog.
5. Measure 429 separately from 503, partial crawl status, and downstream saturation.
6. Drain queues, reconcile runs or batches, and delete test artifacts after the evidence window.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not load-test production or third-party target sites …

Exa Deterministic Local Development Loop

Overview

Build and test an Exa adapter locally using schema fixtures, recorded content-free envelopes, and an explicit opt-in live lane. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Search results, crawl output, and rankings are time-varying. Local tests should own sanitized response fixtures for request and failure shapes, while live calls remain a separately authorized integration lane with a small budget.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Locate the application-owned Exa boundary and its existing tests.
2. Define typed request, response, status, and error-tag fixtures.
3. Cover Search, Contents per-URL statuses, and one retryable failure offline.
4. Inject a fake clock and deterministic retry schedule.
5. Gate any live probe behind explicit credentials and an opt-in flag.
6. Report fixture provenance, assertions, and whether a live call occurred.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not commit real page contents, queries, API keys, or presigned URLs.
• Do not make network access a unit-test prerequisite.
• Do not treat a sanitized fixture as proof that the current vendor contract is unchanged.

Out…

Legacy Search to Exa Migration

Overview

Migrate a legacy web-search integration to Exa through semantic, filter, freshness, relevance, cost, and rollback comparisons. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa publishes a Bing migration guide, but provider fields and ranking semantics are not one-to-one. Exa Search supports domain, date, category, location, moderation, content, and deep-synthesis controls. Migration acceptance must evaluate the application outcome rather than translate parameters mechanically.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Inventory legacy queries, filters, result fields, freshness, quotas, and downstream assumptions.
2. Build a consented evaluation corpus with relevance and safety judgments.
3. Map each requirement to Exa Search or a separate Contents stage.
4. Run shadow comparisons under matched result, freshness, and cost budgets.
5. Canary traffic with output-shape compatibility and a provider rollback switch.
6. Remove legacy credentials only after parity, observation, and stakeholder acceptance.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not equate rank positions across providers.
• A field-name translation can hide different fre…

Exa Multi-environment Isolation

Overview

Separate Exa development, staging, and production credentials, budgets, schedules, data, and observability. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa usage and paid access are organized through teams, and team members share plan features and limits. API keys can have names, rate limits, and budgets when Team Management is enabled. Environment isolation must be designed rather than inferred from a key name.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Inventory teams, organizations, members, service keys, API keys, and owners.
2. Assign each environment an explicit team or documented isolation boundary.
3. Create narrowly named keys with budgets and rate limits where supported.
4. Prevent production keys from preview, developer, and forked-CI contexts.
5. Namespace Monitor, Webset, Agent, Batch, and evidence identifiers by environment.
6. Test revocation, promotion, teardown, and cross-environment denial.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Multiple keys in one team can still share plan and capacity boundaries.
• Copying production data into staging changes the data-governance scope.
• Deleting a deployment does not …

Exa Operational Telemetry

Overview

Instrument Exa calls with content-free metrics, traces, cost, and asynchronous lifecycle signals that support diagnosis without logging retrieved text. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa responses expose request IDs and often costDollars; errors expose status and tags; Contents exposes per-URL statuses. Agent, Monitor, Webset, and Batch operations add IDs, states, queues, events, and terminal outcomes that must be reconciled separately.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Define service-level objectives for each endpoint and asynchronous product.
2. Emit endpoint, status, tag, latency, attempt, result count, and request ID safely.
3. Measure Contents status mix and freshness mode rather than logging page content.
4. Track run age, terminal state, webhook lag, queue depth, and reconciliation drift.
5. Attribute cost by environment, workload, key, product, and owner.
6. Alert on error-class shifts, stalled state, throttling, overload, credit risk, and missing events.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Raw queries, URLs, highlights, summaries, and outputs are not safe default labels.
• HTTP success can hide partial…

Exa Latency and Retrieval Performance Tuning

Overview

Tune Exa search type, content mode, freshness, result count, and concurrency against measured latency and retrieval quality. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Search types trade latency and synthesis depth; content extraction, outputSchema, forced livecrawl, summaries, and subpages add work. Highlights are usually more token-efficient than full text. Published latency values are guidance, not a service-specific SLO.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Build a consented benchmark set with explicit relevance and freshness judgments.
2. Measure the current adapter end to end, including queue and downstream processing.
3. Vary one dimension at a time: type, result count, content mode, freshness, or subpages.
4. Track p50, p95, errors, content size, relevance, freshness, and cost together.
5. Choose separate profiles for interactive, background, and deep-research paths.
6. Canary the winning profile and retain rollback thresholds.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Faster results can be less relevant or stale.
• Forced livecrawl and deep synthesis stack latency rather than replacing it.
• Vendo…

Exa Query and Content Policy Guardrails

Overview

Enforce query, domain, moderation, freshness, content, and downstream-use policy before and after Exa retrieval. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Search supports include and exclude domains, date filters, categories, user location, and moderation, with documented category incompatibilities. These controls reduce scope but do not replace application authorization, content inspection, attribution, or output policy.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Translate the business purpose into allowed query classes, domains, dates, and outputs.
2. Reject secrets, prohibited personal data, and disallowed investigation intent before retrieval.
3. Apply supported Exa filters and moderation without inventing unsupported combinations.
4. Inspect returned URLs, content, citations, and generated fields against the same policy.
5. Quarantine prompt injection, malware, unverifiable claims, and unexpected sensitive data.
6. Log content-free policy decisions and review exceptions with an accountable owner.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Domain allowlists do not guarantee that every page is safe or accurate.
• Company…

Exa Production Readiness Gate

Overview

Gate an Exa-backed service on contract, security, cost, reliability, observability, and rollback evidence. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Production readiness spans the chosen Exa product, not just connectivity. Search and Contents require content and freshness controls; Agent, Monitors, Websets, and Batch add asynchronous state; webhooks add signature and replay handling; every paid surface needs a budget owner.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Freeze the release SHA, adapter version, endpoint inventory, and rollback owner.
2. Verify auth, secret rotation, data classification, domain policy, and moderation.
3. Exercise documented success, partial, throttle, billing, policy, and overload paths.
4. Confirm endpoint budgets, cost alerts, queue bounds, timeouts, and retry ceilings.
5. Verify request IDs, safe metrics, signed-webhook evidence, and deletion procedures.
6. Canary under explicit limits and promote only after the rollback window passes.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• A green Search smoke test does not validate asynchronous or webhook paths.
• Unbounded livecrawl, subpages, summaries, or Agent…

Exa Endpoint Rate-limit Control

Overview

Budget Exa throughput per endpoint and distinguish caller rate limiting from vendor overload and billing exhaustion. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Published defaults are 10 QPS for /search, 100 QPS for /contents, and 10 QPS for /answer, while enterprise limits may differ. A 429 can reflect API-key, team, or network limits and should honor Retry-After when present. A 503 SERVICE_OVERLOADED is a separate capacity signal.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Inventory endpoint mix, team limits, key-specific controls, concurrency, and burst shape.
2. Set independent token buckets for Search, Contents, Answer, Agent, and administrative traffic.
3. Bound queues and propagate deadlines instead of allowing hidden backlog growth.
4. Honor Retry-After and use capped jitter only for retryable classes.
5. Measure attempts, completions, throttles, overloads, queue age, and cost together.
6. Request a limit change only with measured demand and an owner-approved capacity plan.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Adding keys does not prove that team or network capacity increased.
• Retrying 402 or invalid 400 requests wast…

Exa Retrieval Architecture Boundary

Overview

Design an Exa architecture that separates query policy, retrieval, content handling, asynchronous state, citations, and evidence. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Use Search for ranked discovery, Contents for known URLs, Answer for a direct cited response, Agent for multi-step research, Monitors for recurring discovery, Websets for verified and enriched sets, and Batch for enabled enterprise offline volume. Each product has distinct lifecycle and trust boundaries.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Classify the user outcome, latency class, data sensitivity, freshness, and volume.
2. Select the narrowest Exa product that satisfies the outcome.
3. Place policy and credential enforcement before the vendor adapter.
4. Separate retrieved content from content-free operational metadata and citations.
5. Persist only necessary asynchronous IDs and define terminal-state reconciliation.
6. Diagram failure, retention, deletion, webhook, cost, and rollback boundaries.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not use Agent when a bounded Search or Contents call is sufficient.
• Do not feed untrusted retrieved text dire…

Exa Reliability and Retry Design

Overview

Design bounded Exa retries, deadlines, partial-result behavior, and tested fallbacks by endpoint and failure class. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Retryability depends on status and operation. Invalid 400, auth, policy, and billing failures require repair; 429 honors Retry-After; documented transient server or overload failures can use capped jitter. Asynchronous creates and destructive calls require identity and state checks before replay.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Classify each operation as read, create, update, trigger, cancel, stop, or delete.
2. Assign an end-to-end deadline and bounded attempt budget per operation.
3. Retry only documented transient classes and preserve request or resource IDs.
4. Define partial Contents behavior and freshness fallback explicitly.
5. Choose a tested degrade path that preserves source attribution and policy.
6. Exercise timeout, duplicate delivery, stale cache, overload, and recovery in tests.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Retrying a create after an ambiguous timeout can duplicate paid work.
• Serving cache-only content can violate a freshness promise …

Exa SDK Adapter Patterns

Overview

Isolate exa-js or exa-py behind an application-owned adapter that preserves current request semantics and safe evidence. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

The JavaScript and Python SDKs expose Search, Contents, Answer, Agent, and Monitor surfaces with language-specific naming. The adapter should normalize application inputs and errors without inventing defaults, and it should preserve requestId, statuses, grounding, and costDollars needed for operations.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Pin the selected SDK and inspect its current first-party specification.
2. Define the smallest application-owned interface for the required product surface.
3. Map names and optional fields explicitly at the adapter boundary.
4. Return content-free operational metadata separately from retrieved content.
5. Normalize documented errors without erasing status, tag, or request ID.
6. Add fixture-backed contract tests before changing the pinned SDK.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not expose the vendor client throughout business logic.
• Do not assume Python snake_case and TypeScript camelCase are interchangeable.
• Do not…

Exa Security and Data Boundary

Overview

Threat-model Exa credentials, query intent, retrieved web content, generated output, and retained operational evidence as separate trust boundaries. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Exa is SOC 2 Type II certified and offers enterprise controls such as Zero Data Retention and HIPAA enablement. HIPAA mode is request-scoped, supports only eligible Search and Contents cache-only retrieval, and rejects summaries or live freshness. Regional access restrictions can yield Cloudflare block pages rather than Exa JSON.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Classify queries, URLs, retrieved content, outputs, identifiers, and credentials separately.
2. Confirm team plan and enterprise controls before asserting compliance.
3. Keep API and service keys server-side with narrow ownership and rotation.
4. Apply moderation, domain policy, output validation, and prompt-injection defenses.
5. Store only approved evidence and propagate deletion or retention decisions downstream.
6. Test credential revocation, policy denial, regional blocks, and incident escalation.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• SOC 2 certification does not automatical…

Exa SDK and API Upgrade Migration

Overview

Upgrade Exa SDK or API usage through a contract inventory, fixture diff, canary, and reversible dependency change. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Current Search uses auto, fast, instant, deep-lite, deep, and deep-reasoning; neural is legacy terminology for new code. SDK method names and request casing differ by language, and newer product surfaces may be beta-gated. The first-party SDK specifications and changelog are the migration authority.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Record current dependency, lockfile, endpoint calls, types, headers, and feature flags.
2. Read the target SDK specification and Exa changelog for breaking changes.
3. Diff owned fixtures for requests, responses, errors, statuses, and costs.
4. Update only the application adapter and regenerate its lockfile deterministically.
5. Run offline contracts, then an approved synthetic canary on the target version.
6. Retain a dependency rollback and remove compatibility code only after observation.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Do not automatically fall back to an older SDK or search type.
• A compile pass does not prove response, e…

Exa Monitor Webhook Processing

Overview

Receive Exa Monitor events through verified signatures, replay resistance, deduplication, and fast acknowledgment. Treat credentials, queries, retrieved content, generated output, spend, and destructive state as separately governed boundaries.

Prerequisites

• The target repository, environment, Exa team, product surface, and accountable owner.
• The workload's data classification, latency and freshness promise, cost ceiling, and retention policy.
• Current first-party documentation plus credentials only for a narrowly approved live check.

Current Contract

Monitors schedule recurring searches, deduplicate prior results, and deliver to an HTTPS public webhook. The one-time webhookSecret is returned only when a Monitor is created. Exa-Signature carries timestamp and v1 values for HMAC-SHA256 verification over the signed payload; redirects are not followed.

Authentication

For normal REST work, inject EXA_API_KEY from an approved server-side secret manager and send it only as Authorization: Bearer to the configured first-party Exa API host. Team Management service keys, hosted MCP OAuth or enterprise managed authorization, and payment-protocol calls are separate trust models. Never print, commit, place in a URL, or expose a credential to an untrusted client.

Instructions

1. Create or rotate a Monitor only with an approved query, schedule, destination, and budget.
2. Store the one-time webhook secret immediately in the receiver secret store.
3. Verify the raw body timestamp and HMAC using constant-time comparison before parsing.
4. Reject stale, malformed, unsigned, redirected, or unrecognized deliveries.
5. Deduplicate on stable event and run identifiers, acknowledge quickly, and enqueue work.
6. Reconcile webhook processing with the Monitor run API and retain content-free evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect repository code, configuration, fixtures, and evidence. Use Write and Edit only for approved implementation or documentation changes. Do not call Exa, run paid research, create or alter a Monitor, Webset, Agent run, Batch, team, member, API key, budget, webhook, or deployment merely because this skill was invoked.

Approval Boundaries

Require an accountable owner before live queries involving sensitive intent, production credentials, spend or rate-limit changes, forced live crawling, generated summaries, external delivery, deployment, member or key changes, schedule creation, or destructive cancellation, stopping, deletion, or revocation. Read-only repository inspection and synthetic offline validation do not authorize live vendor actions.

Failure Modes

• Never reconstruct a signature from reserialized JSON.
• The secret cannot be fetched…