> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve study results

> Runnable TypeScript example: retrieve study results, with inputs, output, source code, and execution limits.

[Raw TypeScript source](https://raw.githubusercontent.com/user-intuition/examples/main/examples/retrieve-study-results/index.ts) · [Workflow walkthrough](https://github.com/user-intuition/examples/tree/main/examples/retrieve-study-results) · [All examples](/api-reference/developer-examples)

## Run locally

Requires Node.js 22.18 or later. Run from the cloned repository; this file imports the shared client and contracts in `src/`. The default uses fictional local fixtures with no credentials, network calls, invitations, or spending.

```sh theme={null}
git clone https://github.com/user-intuition/examples.git
cd examples
npm run results
```

For live calls, supply `USERINTUITION_API_KEY` securely in the environment and explicitly select `--live`. Follow the walkthrough for action-specific arguments and approvals. The B2/C1 adapters are illustrative pending [release verification](https://github.com/user-intuition/examples/blob/main/docs/release-check.md). Passing fixture checks does not establish live contract compatibility.

## Inputs

Live mode requires --study YOUR\_STUDY\_ID. Add --fetch-source to fetch the first supporting interview.

## Expected output

JSON containing mode, report, and source\_references. With --fetch-source, a second JSON object contains the reference and source\_interview, or a source\_status explaining why none was fetched.

## Side effects

Read-only in live mode; it does not generate a report or start research.

## Failures

Missing credentials or study ID, HTTP failures, invalid JSON, and unresolved source interviews are failures, not empty evidence. Stale or unknown freshness is reported separately.

## Complete source file

The following is generated from `examples/retrieve-study-results/index.ts`, not maintained as a separate snippet. SHA-256: `a2ba59e78bfd70c227e357788a34ed1ccb6424e5915a99bcb419c6247bdda2a3`.

```typescript theme={null}
import { args, required } from "../../src/args.ts";
import {
  ResearchClient,
  fixture,
  output,
  releaseNotice,
} from "../../src/client.ts";
import { routes, sourceReferences, type Report } from "../../src/contracts.ts";
const options = args();
if (options.live) releaseNotice();
const report = options.live
  ? await new ResearchClient().request<Report>(
      "GET",
      routes.report(required(options.study, "study")),
    )
  : await fixture<Report>("report");
output({
  mode: options.live ? "live" : "fictional fixture; no network or spend",
  report,
  source_references: sourceReferences(report),
});
if (report.is_stale === true)
  console.error("This report is stale; retrieval did not regenerate it.");
if (report.is_stale == null) console.error("Report freshness is unknown.");

// Inspect one supporting interview without silently fetching an entire library.
if (options["fetch-source"]) {
  const reference = report.references.find((ref) => ref.interview_id);
  if (!reference?.interview_id) {
    output({
      source_status: "No interview reference is available in this report.",
    });
  } else {
    const interview = options.live
      ? await new ResearchClient().request(
          "GET",
          routes.interview(reference.interview_id),
        )
      : (
          await fixture<Array<{ id: string; messages: unknown[] }>>(
            "interviews",
          )
        ).find((item) => item.id === reference.interview_id);
    if (!interview)
      throw new Error(
        "Referenced interview was not found; do not infer its contents.",
      );
    output({
      reference,
      source_interview: interview,
      instruction:
        "Inspect the original passage. A retrieved interview is not automatic verification of a generated summary.",
    });
  }
}
```