Research Guides
Separate an Accepted Research Job from a Ready Report
A research request returns a successful-looking response, so a dashboard marks the report complete. Minutes later there is still no file to download. The problem may be a missing distinction between accepting work and finishing it.
This guide provides a completion-evidence checklist for asynchronous research jobs. It does not claim that Colquhoun.AI exposes a particular job API or promises a particular processing time.
1. Read accepted as accepted
RFC 9110's definition of HTTP 202 says the request has been accepted for processing, but processing is not complete. The eventual action is not guaranteed. The response ought to describe the current state and identify a status monitor where appropriate.
For a research workflow, acceptance is therefore evidence of submission handling, not evidence that a usable report exists. Keep those two milestones separate in both implementation and customer-facing language.
2. Define the completion contract
Before testing, write down what the particular service documents as its completion signal. It may expose a status endpoint, a callback or a separate result location. Do not invent a polling address from a job identifier or assume that another provider's conventions apply.
Record which output is expected and how it will be matched to the original request. A status labeled complete and a downloadable artifact are related observations, but they are not interchangeable. The artifact still needs to be the right report for the right authorized requester.
3. Trace a fictional report request
Imagine a fictional page-comparison service. A request receives HTTP 202 and a job identifier. Its documented status response later changes from queued to processing, then to completed. The final response supplies an authorized result link.
The reviewer records each observation separately. They follow the result link within the permitted workflow and check the report's requested domains, date range and file type. If the file belongs to an earlier comparison, the transport succeeded but the deliverable check failed.
If the job instead reports failure, the reviewer retains that terminal result. They do not continue presenting the earlier acceptance response as proof of success.
4. Avoid turning uncertainty into duplicate work
A missing result can tempt an operator to submit the same request again. First inspect the existing job through its documented mechanism. Repeated submission may create additional work or charges, depending on the service.
Use only authorized tests, preferably synthetic fixtures or a no-charge test environment. Follow documented polling intervals and retry rules. If no completion mechanism is documented or accessible, report that specific limitation instead of probing unrelated endpoints or promising an outcome.
5. Copy this completion-evidence card
- Request: task description and non-sensitive correlation identifier.
- Acceptance: observed response and timestamp.
- Monitoring contract: documented status or callback mechanism.
- Progress: observed states and times, without guessed transitions.
- Terminal result: completed, failed, canceled or still unresolved according to the service.
- Artifact: verified availability, expected contents and authorized ownership.
- Disposition: delivered, retry approved, investigated or awaiting a known dependency.
Keep credentials and private download tokens out of shared incident notes. The record should make the sequence reproducible without granting another person access to customer material.
6. Match the message to the evidence
After acceptance, say the job was submitted. After observing a running state, say processing is underway. Announce a ready report only when the workflow's completion evidence and the deliverable check support that claim.
If testing ends while the job is pending, state when it was last checked and what remains unknown. A clear pending result is better than a premature success message that forces the reader to discover the missing file.