Kagi Search API: Build a 30-Field Reproducibility Record

The query is only one input

As accessed August 29, 2026, Kagi’s Search API documentation says the API inherits settings from the account that owns the API token. Its examples name blocked or promoted websites and snippet length. Kagi’s May 21, 2026 changelog entry also says API queries can inherit account lenses, upranks, downranks and blocklists.

That contract changes the unit of comparison. A recorded query without its account configuration is an incomplete test input. Two identical query strings can belong to different experimental conditions when they use different account states.

Separate documentation, configuration and observation

The safe conclusion is local: the two captured runs were or were not comparable under the fields you preserved. The record does not reveal Kagi’s full ranking system, and the public documentation does not claim it does.

Freeze an account alias, not a secret

Assign the test account and API key non-sensitive aliases such as ACCOUNT-A and KEY-2026-08. Store the real credential in the approved secret manager. Never place the token in the public ledger, request filename, screenshot, article draft or version control.

The alias is a correlation key. It lets an auditor connect a run to a controlled account record without exposing the account email or API credential. Record who can resolve the alias and when the mapping should be retired in the private test protocol, not in the downloadable CSV.

Snapshot domain personalization

Kagi’s personalized-results documentation lists five domain states: block, lower, normal, higher and pin. It also documents a way to disable personalization for a single search. A test record therefore needs more than a yes-or-no personalization field.

Export or transcribe the domain-rule set into a private canonical file, sort it consistently, and record its SHA-256 hash. The public ledger can retain the hash and counts for blocked, lowered, raised and pinned domains. That proves which private snapshot the run referenced without publishing a personal browsing preference list.

Record lenses and one-search overrides

A lens can narrow or reshape the search context, while a one-search override can temporarily bypass personalization. Record the lens name, whether it was enabled, and the effective personalization state for that request. Do not infer the effective state from what the operator remembers later.

If the interface and API expose different controls, write down which surface supplied the value. A screenshot of an account setting does not prove that a particular API call used it. The request record, account snapshot and observed response must remain separate evidence objects.

Control the request envelope

Freeze these fields before the first request. If a control changes mid-run, start a new run ID rather than editing the earlier record. Reproducibility requires an immutable account of what happened, not a cleaned-up description of what was intended.

Preserve raw evidence privately

Store the complete request and response in a restricted location when policy permits. The downloadable record should point to private artifact references, not contain authentication headers, account identifiers or sensitive query text. Hash the normalized query when the query itself is confidential.

Keep the raw response unchanged. Parsing, URL normalization and deduplication should produce derived files. This mirrors the evidence separation in the retrieval provenance guide: returned tool evidence and later model or application interpretation are different layers.

Compare results at the right unit

Use one row per returned result, not one row per query. Preserve rank, returned URL and resolved domain beside the run-level fields. A changed rank, missing URL, new URL, redirect or snippet-only difference should receive a different classification.

Do not explain every difference with personalization

Search results can change because the index, page content, ranking system, API contract or retrieval time changed. A matching personalization snapshot removes one competing explanation; it does not prove the cause of the remaining difference.

Use language that matches the evidence: “the results differed while the recorded account-state hash matched” is supportable. “Kagi randomly changed the ranking” is not supported by this record. If causal attribution matters, design controlled runs that change one declared input at a time.

Use a paired-run protocol

1. Freeze the API version, endpoint, query set, locale path and account snapshot.
2. Run the baseline and preserve each raw request and response.
3. Change one declared condition, such as disabling personalization for the paired search.
4. Run the comparison within the chosen time window.
5. Normalize URLs with a written rule, then classify observed differences.
6. Have a second reviewer check the account-state references and a sample of URL matches.
7. Record the decision and the next re-audit date.

A short time gap reduces one source of variation but does not freeze the live web or Kagi index. Report the timestamps and treat both responses as dated observations.

Download the 30-field record

Download the Kagi Search API reproducibility record. The unit of analysis is one returned result within one recorded run. Remove both EXAMPLE-REMOVE rows before use.

The template includes evidence, owner, timing, limitations and a release decision. Keep request and response artifacts private when they contain sensitive queries or account information. Validate that every row has 30 columns after editing.

Define re-audit and stop rules

Set the decision due date before collection and name the owner who can accept, hold or reject the comparison. Re-run the protocol after a documented API change, a lens or domain-rule change, a locale-path change, or a time interval that makes the original observation stale for the intended decision.

Stop immediately if a credential appears in an artifact, the account snapshot cannot be matched to the run time, the query set changed without a new version, or raw responses were overwritten. A partial record may still explain what is missing, but it should not support a reproducibility claim.

Release only a bounded conclusion

Approve a comparison only when the query, API surface, locale path and account-state evidence are complete enough for the stated decision. Hold it when a snapshot was taken after the run, a token or account identifier leaked into the package, or the comparison silently mixes presentation and ranking differences.

For cross-system reporting, use the AI visibility measurement crosswalk before translating a result-set difference into a visibility claim. For source handling, use the evidence-led publishing guide. The defensible endpoint is a reproducible record of two dated observations, not a promise that future results will remain identical.