ai_sample_status

Collects the answer to an ai_sample job. FREE — poll as often as you need.

Returns status "pending" or "running" with progress and total_steps while the samples are still going, "complete" with the full distribution once they are done, and "failed" with an error if the job died (a failed job is refunded in full). Typical completion is 30-60 seconds, tail around 130.

WHAT COMES BACK: per business — appearances, appearance_rate, shortlist_rate, mean_rank, mean_shortlist_rank, best_rank, worst_rank, top_pick_count and runs_seen — plus every individual run.

TWO DIFFERENT RANKINGS, DO NOT MERGE THEM. businesses in a run is the platform's LISTING, in the order it emitted cards. recommended_businesses is the SHORTLIST read out of the answer's own prose, in the order the answer argued for it — that is the recommendation, and the two disagree routinely: a business the prose puts third can sit tenth in the listing. Report shortlist_rank when a client asks where an AI recommends them — it is null for a business the answer named in a sentence rather than listed, and those runs are counted in mention_appearances instead of shortlist_appearances. Each entry's mention quotes what the answer actually said. reader_version says which version of that reader produced the shortlist: it is our reading of the answer, not the platform's own listing, so before comparing this job with an older stored one confirm the versions match -- across a bump the numbers are not comparable and a reader improvement reads as a drop. mean_rank and best_rank are listing positions and are null for a business that was never in a listing.

GEMINI HAS NO LISTING AT ALL. It sends no structured business block, so businesses is empty in every gemini run and every gemini figure comes from the prose shortlist. An empty businesses array on gemini is not evidence that nobody was named.

READING THE RATES: every rate is out of samples_returned, which counts only runs that ANSWERED. A failed run and a refusal are both excluded — a run where the model said "I'm having a hard time fulfilling your request" is not a run where the client was absent. Check samples_refused: a high count means the platform is declining the prompt, not that the client is invisible, and per-run outcome says which runs those were. An answer that named nobody IS counted, because that is a real absence. mean_rank averages only the runs that named the business, so a business named 2nd in 3 of 10 runs reads mean_rank 2 and appearance_rate 0.3; do not collapse the two into one score.

cited_domains says which SOURCE the answers cited for each business and in how many runs, most-used first -- an answer sourcing a business from its BBB listing rather than its own site is telling you which page it treats as authoritative, and that is usually the finding a client wants. Note that domain and website on the same row hold a citation too, under names that read as the business's own site.

A business the answers spelled more than one way ("WNY Snow Removal" and "WNY Snow Removal LLC") is reported as ONE row, with every spelling in name_variants -- on gemini there is no cid behind a prose mention, so without that the same business reports two rows at half its real rate each. Only a legal form (LLC, Inc), a bare connector, or a tradeless corporate suffix (Service, Services, Company, Group, Solutions) merges; any word naming a different trade leaves the rows separate, as does a cid. A cited domain separates rows only when it looks like the business's own site -- a directory citation is not evidence of identity. Two rows can still be one business: where one name is the other plus a trade word and both carry the same own-site domain in cited_domains, that is usually one business split across spellings, and its real rate is the two rates added. The split is deliberate -- a chain's branches ("Smith Dental" and "Smith Dental Downtown") share a domain exactly the same way, and nothing in the answer says which case this is. Merging them is yours to decide with context about the business that we do not have; we leave the seam visible rather than guess, because a wrong merge cannot be undone from the payload.

matched_on says how runs were tied together: "cid" is Google's own identifier and is exact, "domain" is domain plus name, "name" is the string alone and is the weakest. Google labels AI Mode cards editorially, so on google_ai_mode prefer the cid.

BILLING: this poll costs nothing, so its credit line reads 0. What the job cost is credits_charged — the submit's reservation less the refund for samples that never completed. Refusals are NOT refunded: the prompt was run and the model answered, it just declined.