FastGPTFastGPT

List Chat Records by Cursor

Retrieve chronological conversation messages around a cursor anchor with automatic turn alignment and bidirectional cursors.

Endpoint Overview

  • Method : POST
  • Path : /api/core/chat/record/getRecords_v2
  • Module : Chat / Chat Records
  • Authentication : Authorization: Bearer <apiKey>—Supports App API Key ( appId optional) and Personal API Key ( appId required); also supports authProxy team member proxy and outLinkAuthData share link (see API Getting Started )
  • Interactive Try-It-Out : Open in Scalar API Explorer (self-hosted instances: replace the origin with <instance>/apidoc/systemopenapi#tag/%E5%AF%B9%E8%AF%9D%E7%AE%A1%E7%90%86/POST/core/chat/record/getRecords_v2 )

Description & Notes

Fetches the latest messages by default in chronological order. Provide at most one of prevId (targets Human turn boundary), nextId , or initialId (targets AI turn boundary). Pass prevCursor / nextCursor directly to prevId / nextId ( null when no further page exists). Returned count may slightly exceed pageSize to complete turn boundaries.

Request Parameters

Request Body ( application/json )

Shared Parameters Across Branches

FieldTypeRequiredDefaultConstraints & Description
chatIdstringNo-Chat ID. maxLength: 1024
loadCustomFeedbacksbooleanNo-Whether to load custom feedback items
typestring (enum)No-Fetch mode controlling message visibility and filtering. Allowed values: normal , outLink , home
includeDeletedbooleanNo-Whether to include soft-deleted messages

Mutually Exclusive Branches ( anyOf )

  • App Chat

Identify the conversation via appId . When both API Key and login session are supported, Authorization takes precedence over token/Cookie.

FieldTypeRequiredDefaultConstraints & Description
appIdstringYes-Application ID authenticated with the request header credentials allowed by this endpoint. pattern: ^[0-9a-fA-F]{24}$
sourceTypestring (enum)No-Session resource type associated with appId . Defaults to app ; pass the matching sourceType for assistant builder sessions. Allowed values: app , chatAgentHelper , workflowBuilder

Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.

Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.

FieldTypeRequiredDefaultConstraints & Description
customUidstringYes-Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024

Proxy Team Member ( authProxy ): Act on behalf of another member in the same team via authProxy . Available only on personal API keys with authProxy enabled; mutually exclusive with customUid .

FieldTypeRequiredDefaultConstraints & Description
authProxyobjectYes-API Key proxy caller identity. Available only for personal keys with authProxy enabled; specify tmbId or username ( tmbId takes precedence without falling back to username on invalid ID).
authProxy.tmbIdstringYes-Branch: By Team Member ID . Proxied team member ID ( tmbId ), takes precedence over username . pattern: ^[0-9a-fA-F]{24}$
authProxy.usernamestringYes-Branch: By Username . Proxied team member username. minLength: 1; maxLength: 128
  • Skill Debug Session

Identify the debug session via skillId (takes precedence over appId and ignores sourceType ), authenticated with allowed request header credentials.

FieldTypeRequiredDefaultConstraints & Description
skillIdstringYes-Skill Edit debug ID authenticated with allowed request header credentials. pattern: ^[0-9a-fA-F]{24}$
  • Share-Link Chat

Resolves the underlying app via outLinkAuthData , taking precedence over skillId and appId (ignoring sourceType ). Protected links still validate login cookies/tokens and never fall back to standard auth on failure.

FieldTypeRequiredDefaultConstraints & Description
outLinkAuthDataobjectYes-Share-link auth payload ( shareId / outLinkUid ). Overrides skillId and appId ; protected links still validate login session cookies/tokens.
outLinkAuthData.shareIdstringYes-Share link ID. minLength: 1
outLinkAuthData.outLinkUidstringYes-External share user ID. minLength: 1
  • App API Key (no appId required)

When authorizing with an app-bound App API Key, omit appId and sourceType ; the server resolves the bound app with sourceType fixed to app . Personal keys and login sessions cannot omit appId , and an explicit appId does not override an App API Key binding.

Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.

Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.

FieldTypeRequiredDefaultConstraints & Description
customUidstringYes-Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024

Shared Parameters Across Branches

FieldTypeRequiredDefaultConstraints & Description
anchorobject | array | string | number | boolean | nullNo-Current anchor position (such as chunkIndex )

Mutually Exclusive Branches ( anyOf )

  • Page Backward ( prevId )
FieldTypeRequiredDefaultConstraints & Description
prevIdstringYes-Cursor data ID for paging backward
pageSizeintegerNo20Mutually Exclusive Group: Pagination Parameters . Target messages per page (default 20, max 500; may be slightly exceeded to complete turn boundaries). max: 500
  • Page Forward ( nextId )
FieldTypeRequiredDefaultConstraints & Description
nextIdstringYes-Cursor data ID for paging forward
pageSizeintegerNo20Mutually Exclusive Group: Pagination Parameters . Target messages per page (default 20, max 500; may be slightly exceeded to complete turn boundaries). max: 500
  • Anchor Record ( initialId )
FieldTypeRequiredDefaultConstraints & Description
initialIdstringYes-Initial anchor message data ID
pageSizeintegerNo20Mutually Exclusive Group: Pagination Parameters . Target messages per page (default 20, max 500; may be slightly exceeded to complete turn boundaries). max: 500
  • Default Latest Page
FieldTypeRequiredDefaultConstraints & Description
pageSizeintegerNo20Mutually Exclusive Group: Pagination Parameters . Target messages per page (default 20, max 500; may be slightly exceeded to complete turn boundaries). max: 500

Request Examples

Replace YOUR_API_KEY and placeholder IDs before running. Self-hosted users should replace the base URL with <instance>/api .

cURL Example

curl --fail-with-body -X POST "https://cloud.fastgpt.io/api/core/chat/record/getRecords_v2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "appId": "68ad85a7463006c963799a05",
  "prevId": "68ad85a7463006c963799a04"
}'

Minimal Valid JSON Body

{
  "appId": "68ad85a7463006c963799a05",
  "prevId": "68ad85a7463006c963799a04"
}

Response Schema & Examples

Successful /api/* calls return the standard FastGPT envelope { "code": 200, "statusText": "", "message": "", "data": ... } , where data matches the 200 schema below (when a payload schema is declared; otherwise refer to the status description for runtime data semantics).

HTTP 200

Successfully returned chat records

Content-Type : application/json

FieldTypeRequiredDefaultConstraints & Description
hasMorePrevbooleanYes-Whether earlier messages exist before the current slice
hasMoreNextbooleanYes-Whether newer messages exist after the current slice
listobject[]Yes-Chronological list of chat records (use dataId as the canonical identifier)
totalintegerYes-min: -9007199254740991; max: 9007199254740991
prevCursorstring | nullYes-Cursor dataId for paging backward ( prevId ; server locates the Human turn start; null when unavailable)
nextCursorstring | nullYes-Cursor dataId for paging forward ( nextId ; server locates the AI turn end; null when unavailable)

Polymorphic Field: list

  • Variant 1 ( obj="Human" ): obj , value , hideInUI , useAgentSandbox , totalQuoteList , toolCiteLinks , errorText , llmModuleAccount
  • Variant 2 ( obj="System" ): obj , value , useAgentSandbox , totalQuoteList , toolCiteLinks , errorText , llmModuleAccount , historyPreviewLength
  • Variant 3 ( obj="AI" ): obj , value , memories , userGoodFeedback , userBadFeedback , customFeedbacks , adminFeedback , isFeedbackRead
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.