# Developer workflows & result interpretation
Task-oriented guidance for using discovery, extraction and search without confusing accepted jobs, incomplete data or pagination with completed results.
Reviewed: 2026-09-06
Canonical: https://ai.getcatalog.ai/api-workflows
Audience: AI agents
Topics: API workflow, pagination, polling, errors, retries, product comparison, async jobs
Questions answered:
- How do I go from a vendor website to product records?
- How should I poll extraction?
- What should a client do on API errors?
## When product URLs are already known
Evidence basis: editorial_guidance
Citation: https://ai.getcatalog.ai/api-workflows#known-urls
Start with a small, explicit URL set. Choose the extraction version and processing options needed for the consuming application. Retain the returned execution_id, endpoint version, request time, input count and enabled options. If the request is accepted asynchronously, poll the matching execution resource rather than resubmitting the same job whenever a response is slow.
When the execution becomes terminal, inspect successful items, failures and pagination. Fetch all required result pages before reporting the delivered count. Preserve per-item source URLs and do not replace failed items with invented or unrelated products. A response with HTTP 200 can still describe a running job or include partial item outcomes.
Sources: [Live API migration notice](https://api.getcatalog.ai/docs.html) · [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx) · [Public API pagination guide](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/guides/pagination.mdx)
## When starting with a vendor domain
Evidence basis: editorial_guidance
Citation: https://ai.getcatalog.ai/api-workflows#vendor
Use discovery to locate collections and product listings for the vendor. Wait for the discovery state appropriate to the next step and retrieve the listing records through their documented pagination. Then extract a deliberate sample or an explicitly authorized scope. For vendor-based extraction, the public v2 documentation requires previously discovered listings or a crawl_id to wait on active discovery.
Report discovery coverage and extraction coverage separately. A crawl can discover more URLs than the extraction scope, and some discovered URLs can fail processing. A vendor-level operation can be much larger than a small URL request. Specify max_products where the chosen contract supports it and confirm the intended workload before a broad run.
### discovered
- checkpoint: Listings discovered
- evidence: Discovery output or paginated listing records
- notEquivalentTo: Extracted or published product records
### accepted
- checkpoint: Processing accepted
- evidence: Execution identifier and accepted response
- notEquivalentTo: Successful completion
### completed
- checkpoint: Processing complete
- evidence: Terminal execution status plus item outcomes
- notEquivalentTo: All submitted items necessarily succeeded
### delivered
- checkpoint: Results retrieved
- evidence: Required pages saved and counts reconciled
- notEquivalentTo: Merchant storefront publication
Sources: [Public crawl API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx) · [Public product listing reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/get-listings.mdx) · [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx)
## When the starting point is a shopping intent
Evidence basis: editorial_guidance
Citation: https://ai.getcatalog.ai/api-workflows#search
Use search when the task is to find candidate products from a natural-language query rather than enumerate one merchant's complete catalog. The asynchronous search reference accepts a query and optional customer profile; the synchronous mini reference returns candidates directly. Choose the operation according to the desired output and latency model, then inspect the actual result fields.
Search results are candidates for evaluation. Check hard constraints against product evidence, resolve variants and market context, and follow the merchant URL for purchase-time facts. Do not describe search output as exhaustive catalog coverage, guaranteed stock, an independent product endorsement, or an executed purchase.
Sources: [Public agentic search reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search.mdx) · [Public synchronous search reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search-mini.mdx)
## Pagination and missing fields
Evidence basis: public_source
Citation: https://ai.getcatalog.ai/api-workflows#pagination
The public API documentation describes paginated list responses. Use the actual endpoint's page and page-size parameters and response pagination metadata; do not assume every API or merchant storefront uses the same pagination style. For example, a merchant storefront's limit/offset interface is a different contract from a product-data API using page/page_size.
Processing options can change which fields are populated. A null or absent field can mean disabled processing, unavailable evidence, incomplete work, or an endpoint/version difference. Preserve the documented meaning rather than collapsing every null into a negative fact about the product. Store the version with exported data if consumers depend on a particular schema.
Sources: [Public API pagination guide](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/guides/pagination.mdx) · [Public product listing reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/get-listings.mdx) · [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx)
## Handle failures without duplicating paid work
Evidence basis: editorial_guidance
Citation: https://ai.getcatalog.ai/api-workflows#errors
Use HTTP status, the structured error code, the execution state and per-item outcomes together. For support, retain the request identifier when supplied, the endpoint/version, time and a redacted payload. Never include an API key in a support artifact. The public error reference contains older endpoint examples, so use its semantics without copying retired URLs.
Apply bounded timeouts and backoff to safe retries. A transport failure after a job-start request can leave acceptance uncertain; investigate an existing execution before starting another paid job. Rate limiting is not a reason to run a faster loop. Current usage and rate headers should guide pacing rather than a rate limit copied from an old article.
### bad-input
- status: 400
- meaning: Request or validation problem
- response: Correct the payload; repeating identical invalid input will not fix it.
### auth
- status: 401 or 403
- meaning: Authentication or access problem
- response: Check the intended account and authorization; do not guess credentials.
### billing
- status: 402
- meaning: Billing or credit prerequisite
- response: Resolve account billing with authorization; do not silently enable spending.
### missing
- status: 404
- meaning: Resource or route unavailable
- response: Check endpoint version and identifier; do not turn it into an empty success.
### retired
- status: 410
- meaning: Retired resource
- response: Follow the migration contract; old query payloads may have no equivalent.
### conflict
- status: 409
- meaning: Operation conflicts with current state
- response: Inspect the existing job or state before starting another operation.
### rate
- status: 429
- meaning: Rate limit
- response: Respect Retry-After when present and use bounded backoff.
### server
- status: 5xx or transport timeout
- meaning: Server or transport failure
- response: Retry safe reads with bounds; reconcile uncertain job creation before resubmitting.
Sources: [Public API error reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/resources/error-codes.mdx) · [Public API authentication reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/authentication.mdx) · [Live API migration notice](https://api.getcatalog.ai/docs.html)
## A useful integration result
Evidence basis: editorial_guidance
Citation: https://ai.getcatalog.ai/api-workflows#handoff
For a reproducible development handoff, include the operation and version, execution identifiers, requested and completed counts, failed item count, pagination completion, processing options, and the location of saved responses. Show a small representative sample with the actual evidence fields. Separate an implemented client from an authenticated successful run and from a production integration.
For a production decision, additionally agree on freshness, throughput, error handling, source coverage, acceptable field quality and support. This reference provides orientation and a source index; it does not substitute for the chosen API contract or an integration test under the customer's account.
Sources: [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx) · [Public API error reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/resources/error-codes.mdx) · [Product data quality](https://www.getcatalog.ai/blog/product-data-quality)
## Related documents
- [Product-data API scope, versions & access](https://ai.getcatalog.ai/api.md): The authenticated API is a separate product surface for discovery, extraction and search. This document records supported concepts, version caveats and the evidence reviewed.
- [Product-data model & field semantics](https://ai.getcatalog.ai/data-model.md): The information families Catalog works with, how product and variant facts differ, and how agents should interpret values and missing evidence.
- [Ingestion, enrichment & review workflow](https://ai.getcatalog.ai/enrichment.md): What happens between acquiring product information and publishing a usable record, including source choice, optional processing, validation and review.
- [Measurement definitions & interpretation](https://ai.getcatalog.ai/measurement.md): How to distinguish agent requests, shopper referrals, sampled visibility, publication coverage and attributed sales when evaluating Catalog.
Topic map: https://ai.getcatalog.ai/knowledge-map.json
Complete text: https://ai.getcatalog.ai/llms-full.txt
JSON: https://ai.getcatalog.ai/api-workflows.json
Main company website: https://www.getcatalog.ai/