Imagine asking three job boards for remote Python roles. One returns records. One cannot apply the remote filter. The third is unavailable. A single successful response containing fourteen jobs hides two important facts: the search did not cover every source, and one source could never have satisfied your request.
By TrueFetch editorial · Method and corrections
Read the outcome in order
- Was the request accepted? A refusal is not an empty search.
- Has execution ended? A running task has not answered yet.
- Which sources completed, failed or were excluded?
- Were matches found within the completed scope?
Use the response reference to distinguish request, task and source outcomes.
A decision guide for an empty result
- Was the request accepted?
No → correct the refusal. No collection result exists to interpret.
- Is the task terminal?
No → read the existing task handle. Do not submit duplicate work.
- Did the requested scope complete?
No → inspect failed or excluded sources. Use partial output only when it was authorized.
- Did any eligible records match?
No → report no matches within the checked scope. Yes → validate the returned records for your application.
Outcome glossary
| Term | What it establishes |
|---|---|
| Succeeded | The eligible requested scope completed, including a valid zero-match answer. |
| Partial | Authorized useful delivery with named gaps; it does not establish full coverage. |
| Failed | No acceptable task result was delivered. It is not a successful empty search. |
| Excluded source | The source was not executed for this scope, for example because a required filter was unsupported. |
| Failed source | An attempted source could not deliver; its outcome remains distinct from the overall task. |
Success needs a scope
A completed search with no matches is a useful answer. A source that could not be reached has not answered the question at all. Treating both as an empty list makes downstream decisions look more certain than they are.
TrueFetch is designed to preserve that distinction. A response identifies which sources delivered, which were excluded before execution, and which failed. The combined outcome describes the request as a whole.
Partial is a choice
Some workflows benefit from anything useful that comes back. Others need all selected sources. That choice belongs to the caller, so partial delivery must be explicitly allowed. Without it, an incomplete task cannot masquerade as a complete one.
A filter is not a suggestion
If a board cannot support a requested filter, quietly dropping it returns records that may not meet your criteria. The design checks source support before collection. An unsupported combination is refused, or the source is excluded when the request explicitly permits that behavior.
The receipt should explain the charge
For Job Search, the planned billing unit is a delivered record. The response should show the eligible quantity and amount, rather than forcing the caller to infer cost from a separate dashboard. A failed source is not a delivered record.
Our illustrative receipt shows fourteen records at an example rate of 1 credit each: 14 credits. That arithmetic explains the model. It is not a published price or a claim of current source coverage.
Helpful for software. Essential for agents.
An AI client deciding whether to answer, retry or ask the user needs the same distinctions as a carefully written application. A structured response cannot guarantee good reasoning, but it can avoid hiding the evidence the client needs.
Inspect the example ↗