How to Fetch Xiaohongshu Data in Batches With Aident Loadout

Yes, a client can use Aident Loadout from server-side code to fetch Xiaohongshu, also known as RedNote, notes and account data in batches. Log in with the Loadout CLI, export the short-lived access_token as AIDENT_TOKEN, preflight every distinct request shape, and call the production HTTP endpoints described by the public Xiaohongshu OpenAPI schema.

This tutorial is for a developer building a batch worker, research pipeline, or internal data-enrichment job. By the end, you will have one authenticated Node.js client, a bounded note-detail batch, a bounded keyword-search batch, and a clear record of estimated and actual Loadout credit usage.

What You Can Fetch

The production action set exposed these operations when it was inspected on August 11, 2026:

Prices and schemas can change. The estimate is dated evidence, not a permanent price list. Preflight the exact action and input before execution, especially for a large batch.

RedFox access for this action set is managed by Aident. The client does not need to supply a separate RedFox API key or sign in to a Xiaohongshu account. Xiaohongshu also operates official platforms for mini apps, sharing, advertising, and commerce. Those platforms serve different jobs from this public-content retrieval workflow.

Prerequisites

• An Aident account with permission to use Loadout and enough credits for the batch.

• A trusted macOS or Linux machine.

• Node.js 18 or newer for the examples.

• Server-side or worker-side execution. Never put AIDENT_TOKEN in browser JavaScript.

• A reviewed collection policy covering the data you are allowed to retrieve, retain, and process.

1. Install Loadout and Log In

Follow https://aident.ai/SETUP.md

For a named client, run first-time setup against production:

aident setup \
  --base-url "https://loadout.aident.ai" \
  --client-name "Xiaohongshu batch worker" \
  --json

If setup is already complete, refresh the login:

aident login --base-url "https://loadout.aident.ai"

On a terminal without a usable browser, add --oob. Open the displayed URL on a trusted device, authorize the client, and paste only the authorization code into the waiting terminal.

Confirm the session before doing anything billable:

aident account auth status --json

The expected response has success: true, data.authenticated: true, and the intended Aident account identity.

2. Find AIDENT_TOKEN Without Printing It

After login, the CLI stores its OAuth credentials in ~/.aident/credentials.json. The value needed for the HTTP Authorization header is access_token. It is not client_id or refresh_token.

Refresh the CLI-managed session, then export the access token without displaying it:

aident account auth status --json >/dev/null

export AIDENT_TOKEN="$(
  node -e '
    const fs = require("node:fs");
    const os = require("node:os");
    const path = require("node:path");
    const file = path.join(os.homedir(), ".aident", "credentials.json");
    const credentials = JSON.parse(fs.readFileSync(file, "utf8"));
    if (!credentials.access_token) process.exit(1);
    process.stdout.write(credentials.access_token);
  '
)"

test -n "$AIDENT_TOKEN"

The last command succeeds without revealing the token. Keep shell tracing off because set -x can expose expanded headers. For a deployed worker, use the platform's secret manager instead of copying a developer token into source or configuration files.

Access tokens expire. Before each direct-HTTP batch, run aident account auth status --json and export the current access_token again. Do not share a developer refresh token among services.

3. Download the Public OpenAPI Contract

The client-focused OpenAPI 3.1 document is public at:

https://aident.ai/assets/loadout/openapi/xiaohongshu.yaml

Download it into the client project:

curl --fail-with-body --silent --show-error \
  "https://aident.ai/assets/loadout/openapi/xiaohongshu.yaml" \
  --output xiaohongshu-loadout.yaml

The schema defines authentication status, metadata, preflight, execution, and audit operations plus all nine action input variants. It also binds the exact Loadout capability discriminator required by the API. Generate an SDK from this document or let the sample resolve the discriminator from the checked-in copy instead of hardcoding an internal identifier from an old article.

This small Node command reads that constant from the downloaded schema without printing a credential:

export LOADOUT_XIAOHONGSHU_CAPABILITY="$(
  node -e '
    const fs = require("node:fs");
    const yaml = fs.readFileSync("xiaohongshu-loadout.yaml", "utf8");
    const block = yaml.match(/^    CapabilityName:\n([\s\S]*?)(?=^    \S)/m)?.[1];
    const value = block?.match(/^      const: (.+)$/m)?.[1];
    if (!value) process.exit(1);
    process.stdout.write(value.trim());
  '
)"

test -n "$LOADOUT_XIAOHONGSHU_CAPABILITY"

4. Create a Shared Preflight-First Client

Save this as loadout-xiaohongshu.mjs:

const token = process.env.AIDENT_TOKEN;
const capabilityName = process.env.LOADOUT_XIAOHONGSHU_CAPABILITY;
const baseUrl = 'https://loadout.aident.ai/api/openapi/loadout';

if (!token || !capabilityName) {
  throw new Error('Set AIDENT_TOKEN and LOADOUT_XIAOHONGSHU_CAPABILITY first');
}

async function call(operation, body) {
  const response = await fetch(`${baseUrl}/${operation}`, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${token}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  const envelope = await response.json();
  if (!response.ok || !envelope.success) {
    const code = envelope.error?.code ?? `http-${response.status}`;
    throw new Error(`${code}: ${envelope.error?.message ?? response.statusText}`);
  }
  return envelope.data;
}

export async function preflightAndExecute(input) {
  const request = { name: capabilityName, input };
  const preflight = await call('loadout_capabilities_preflight', request);

  if (!preflight.inputValid) {
    throw new Error(`Invalid input: ${JSON.stringify(preflight.validationIssues)}`);
  }
  if (preflight.creditApproval) {
    throw new Error(`Explicit credit approval required: ${preflight.creditApproval.message}`);
  }

  const execution = await call('loadout_capabilities_execute', request);
  return {
    estimate: preflight.estimate ?? null,
    durationMs: execution.durationMs,
    output: execution.output,
  };
}

export async function mapLimit(items, limit, fn) {
  const results = new Array(items.length);
  let nextIndex = 0;

  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
    while (nextIndex < items.length) {
      const index = nextIndex++;
      results[index] = await fn(items[index], index);
    }
  });

  await Promise.all(workers);
  return results;
}

The helper deliberately stops when preflight requests explicit credit approval. Approval must come from the client and must apply to the exact input-bound request. Do not turn a one-time approval token into a standing budget bypass.

5. Sample One: Fetch a Bounded Batch of Note Details

Save this as fetch-note-details.mjs:

import { mapLimit, preflightAndExecute } from './loadout-xiaohongshu.mjs';

const items = [
  {
    id: 'client-row-001',
    workLink: 'https://www.xiaohongshu.com/explore/REPLACE_ME_1',
  },
  {
    id: 'client-row-002',
    workId: 'REPLACE_ME_2',
  },
];

const results = await mapLimit(items, 3, async (item) => {
  const input = {
    actionName: 'xhs_user_query_work_detail',
    ...(item.workId ? { workId: item.workId } : { workLink: item.workLink }),
  };
  const result = await preflightAndExecute(input);
  return { id: item.id, ...result };
});

process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);

Run it with:

node fetch-note-details.mjs > note-details-results.json

Each row should contain the stable client ID, the preflight estimate, execution duration, and raw provider output. The provider output is intentionally open-ended in the schema, so preserve the raw object and version any downstream normalization separately.

Send exactly one of workId or workLink. The current server schema permits an identifier-free request, but a client should reject it before submission.

6. Sample Two: Search Notes Across Several Keywords

Save this as search-notes.mjs:

import { mapLimit, preflightAndExecute } from './loadout-xiaohongshu.mjs';

const keywords = ['AI Agent', '露营装备', '咖啡店探店'];

const results = await mapLimit(keywords, 2, async (keyword) => {
  const result = await preflightAndExecute({
    actionName: 'xhs_user_search_article',
    keyword,
    offset: 0,
  });
  return { keyword, ...result };
});

process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);

Run it with:

node search-notes.mjs > note-search-results.json

Keep keyword count, concurrency, pagination, and time windows bounded. Record which input produced each output so failed rows can be retried without replaying the entire batch.

For larger database queries, use parse_work_query_xhs_ai_msgs and set keyword, pageNum, pageSize, startTime, and endTime explicitly. Do not inherit time defaults in a scheduled job.

7. Inspect Usage After the Batch

The public contract also includes the Loadout audit operation. Ask for recent usage from your own account and filter it to the relevant integration or request source. Reconcile the returned rows with your stable client IDs, estimates, successful outputs, and failures.

Preflight is not the receipt. It validates and estimates. The audit and the returned execution envelope are the evidence that a call actually ran.

Common Failures

401 or an unauthenticated status

Run aident login, then aident account auth status --json. Export the newly refreshed access_token again. Confirm the worker is using the production base URL and the intended account.

validation-error

Compare the input with the current public schema and live metadata. Check the action name, required fields, and primitive types. For note details, include exactly one stable identifier.

credit-approval-required

Stop and present the estimate to the client. If approved, use only the one-time, input-bound approval token returned for that request. The sample stops intentionally rather than approving spend automatically.

requires-user-acknowledgement

Stop and show the risk message and allowed acknowledgement scopes. Credit approval and risk acknowledgement are separate decisions.

A submit action returns a task ID

Comment collection and video-to-copy extraction are asynchronous. Store the returned task ID, then poll the matching result action with bounded backoff. Do not resubmit the paid starter action merely because the result is not ready yet.

The output shape changes

Treat raw provider output as an external contract. Preserve it, validate the fields your application needs, and version your normalization layer. Do not silently coerce missing fields to plausible values.

Production Checklist

Before scheduling a large batch:

1. Confirm the Aident account and token are current.

2. Download or regenerate the client from the current OpenAPI schema.

3. Preflight every distinct action and input shape.

4. Set hard limits for items, pages, date windows, concurrency, timeouts, and credits.

5. Require explicit approval when preflight asks for it.

6. Persist stable client IDs, task IDs, estimates, envelopes, and audit receipts.

7. Retry only retryable rows, with bounded backoff and idempotent bookkeeping.

8. Keep credentials server-side and redact authorization headers from logs.

9. Collect only data the client is authorized to use, and apply retention and privacy controls.

For the wider integration model, see How to Use Aident Loadout, MCP vs API, and How to Give AI Agents API Access Without Exposing Keys.

Set up Aident Loadout for a bounded Xiaohongshu batch, then generate your client from the public OpenAPI contract.

Refresh Triggers

Refresh this guide when the public schema, action list, pricing, authentication flow, approval contract, or official Xiaohongshu platform boundaries change, or when complete owned search evidence identifies a narrower reader job that deserves its own canonical page.

Sources

• Aident Loadout Xiaohongshu OpenAPI schema

• Aident Loadout setup instructions

• OpenAPI Specification 3.1

• OAuth 2.0 Bearer Token Usage

• Xiaohongshu Mini Program Open Platform

• Xiaohongshu Sharing Open Platform

• Xiaohongshu Marketing Open Platform

• Live Aident Loadout catalog, authentication status, preflight, and Vault status, inspected August 11, 2026