Read as Markdown · Use with an AI agent
Data availability and coverage
A successful request describes the data returned for that request. It does not establish complete platform history, a fresh source fetch or the absence of other records.
Preserve the difference between data states
| State | Meaning and handling |
|---|---|
| Value, including 0 or false | Use the value with its documented units and scope. A reported zero is different from an unavailable count. |
| null | A value is explicitly unknown or unavailable. Do not replace it with zero, an empty string or an estimate. |
| Absent field | The optional field was not supplied. Check the selected endpoint schema rather than assuming another platform’s shape. |
| Empty items | This request returned no normalized rows. It does not prove no matching source records exist. |
| Warnings / partial result | Keep usable data and inspect warnings and component outcomes before drawing a conclusion. |
Read completeness at the correct level
The envelope can carry _completeness.state: partial, complete or unknown. Bundle fields such as complete, partial and legs refer to requested components and bounded pages. They do not establish complete account history. data._warnings records reported limitations; array payloads can carry warnings on the envelope. inspection_limited indicates that inspection itself was bounded.
A source fallback may expose fewer optional fields or different continuation support. Inspect the returned metadata instead of assuming a successful fallback matches every field of an earlier response. Absence of warnings is not a guarantee that all fields or records were supplied.
Separate a page, a sample and a full history
Follow the selected endpoint’s cursor or next_params contract. Preserve filters and opaque tokens. A null cursor can mean unavailable or unknown continuation; has_more: null is unknown. Nested collections may continue independently. An aggregate comment or follower count does not promise that many retrievable rows.
Do not infer chronology from row position. Ranked results, pinned posts and changing source order can cause overlap between pages. Deduplicate with stable identifiers while keeping unidentified rows and the original receipts. Document maximum pages and the stop reason in exports.
Choose coverage before collection
| Question | What to verify |
|---|---|
| Which market? | Marketplace, country and currency are separate concepts. Keep the resolved market with product and review records. |
| Which date range? | Use only declared filters. Check whether they constrain publication time, ranking or a coarse source bucket. |
| Which language or geography? | Language and regional ranking do not prove an author’s nationality, residence or audience location. |
| Which population? | Search results, account feeds, reviews, comments and followers have different coverage boundaries. |
| Which fields? | A search preview can require a separate detail lookup; check the endpoint’s field schema before paying for collection. |
Keep provenance and freshness with the result
Store source URLs and identifiers, source publication times when present, your retrieval time, request_id, cached and warning metadata. cached: false does not prove the source itself was refreshed immediately. A fresh fetch can still encounter deleted records or missing fields.
Cache controls are endpoint-dependent and may incur normal retrieval charges. Use the cache guide before forcing a fresh fetch. For analysis, distinguish reported source counters, arithmetic over the returned sample and AI-generated interpretation.