API reference / Chart Analysis

List analyses

List the chart analyses in one channel, newest first, with optional filters for status, direction and timeframe.

Last updated 26 Sep 2026API v1

Method: GET
Path: https://api.returning.ai/v1/analysis/communities/{communityId}/channels/{channelId}
Permission: sendMessage
Retries: Read-only; exact retries are safe

When to use this

Check what a chart channel already shows before you post another analysis.
Find the analysis you just posted after a timeout, before you retry the create.
Sync a channel's open (Pending) analyses into your own tools.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: sendMessageShown in the dashboard as “Send Messages”

Use a Community API key with sendMessage, shown in the dashboard as Send Messages, and keep it on your server. Send your own community's ID and one of its channels. Personal API keys are not accepted here and return 401.

Behaviour#

This read changes nothing. Results are newest first unless you set sortBy and sortOrder. Filters combine. direction is lower case (bullish), while Create analysis takes BULLISH; the upper-case value returns 400.

A channel that doesn't exist, or has no charts, returns 200 with an empty list rather than an error. Read every page up to totalPages, or while hasNextPage is true.

Request#

Path parameters#

communityId#stringREQUIRED

Your community's ID.

Rule24 hex characters

Eg"66f000000000000000000010"

channelId#stringREQUIRED

The chart channel to list. A channel with no analyses, including a channel without charts, returns an empty list.

Rule24 hex characters

Eg"66f000000000000000000b11"

Query parameters#

status#stringOPTIONAL

Only analyses with this status. all, or leaving it out, returns every status.

RulePending, Active, Expired, Cancelled or all

EgPending

direction#stringOPTIONAL

Only analyses with this direction. Lower case here, unlike metadata.direction on Create analysis.

Rulebullish, bearish or all

Egbullish

timeframe#stringOPTIONAL

Only analyses on this chart timeframe.

RuleM1, M5, M15, M30, H1, H2, H4, D, W, M or all

EgH1

sortBy#stringOPTIONAL

What to sort by.

RulecreatedAt, updatedAt or status; default createdAt

EgcreatedAt

sortOrder#stringOPTIONAL

Sort direction. desc, the default, puts the newest first.

Ruledesc or asc

Egdesc

page#integerOPTIONAL

Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#integerOPTIONAL

Analyses per page.

RuleDefault 20

Eg20

Headers#

Authorization#stringREQUIRED

Community API key with sendMessage.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/analysis/communities/66f000000000000000000010/channels/66f000000000000000000b11?status=Pending&page=1&limit=20' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the page in data.analyses and the totals in data.pagination. Each analysis has the same fields as in Get analysis: find the title in extra.analysisType.title, the status in extra.status, and your levels and metadata in the shapes item whose key is analysis. The channel post itself is not included.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

message#stringALWAYS

Human-readable summary. Do not branch on it.

Eg"Analyses fetched successfully"

data#objectALWAYS

This page of analyses and the paging totals.

Eg{ ... }

analyses#object[]ALWAYS

The analyses on this page. Each one has the same fields as data.analysis in Get analysis, without message. Empty when nothing matches.

Eg[ ... ]

_id#string

The analysis ID. Use it with Get, Update, Append drawings and Delete.

shapes#object[]

The card (the item with key analysis, holding levels and metadata) followed by its drawings.

extra#object

Summary values, including status, the lower-case direction, currency_pair and analysisType.title.

timeframe#string

Chart timeframe.

Eg"H1"

createdAt#string

When the analysis was created.

RuleDate-time

Eg"2026-09-27T08:05:12.431Z"

updatedAt#string

When the analysis last changed.

RuleDate-time

Eg"2026-09-27T08:05:12.431Z"

pagination#objectALWAYS

Paging totals for everything that matches.

Eg{ ... }

page#integer

The page you asked for.

limit#integer

The page size used.

Eg20

total#integer

Analyses that match, across all pages.

Eg1

totalPages#integer

Pages at this limit. 0 when nothing matches.

hasNextPage#boolean

true when a later page has analyses.

hasPrevPage#boolean

true when page is above 1.

{
  "status": "success",
  "statusCode": 200,
  "message": "Analyses fetched successfully",
  "data": {
    "analyses": [
      {
        "_id": "66f000000000000000000b01",
        "owner": {
          "id": "3247779"
        },
        "tempId": null,
        "serverId": "66f000000000000000000010",
        "topicId": "66f000000000000000000b11",
        "commentId": "66f000000000000000000b21",
        "timeframe": "H1",
        "users": {
          "up": [],
          "down": []
        },
        "shapes": [
          {
            "key": "analysis",
            "levels": {
              "pivot": {
                "price": 1.1,
                "clientObjectId": "pivot_main",
                "time": "2026-09-27T08:00:00.000Z"
              },
              "resistance": {
                "price": 1.12,
                "clientObjectId": "resistance_main",
                "time": "2026-09-27T08:00:00.000Z"
              },
              "support": {
                "price": 1.08,
                "clientObjectId": "support_main",
                "time": "2026-09-27T08:00:00.000Z"
              }
            },
            "metadata": {
              "direction": "BULLISH",
              "entryPlacement": "BELOW_CURRENT",
              "expiry": {
                "type": "HOURS",
                "hours": 24
              },
              "title": "EURUSD bounce from support",
              "preferenceText": "Holding above [[support_main:support]], targeting [[resistance_main:resistance]].",
              "timeframe": "H1",
              "symbol": "EURUSD"
            },
            "id": "66f000000000000000000b41",
            "isRaw": true,
            "timeRange": [1790496000000, 1790496312431]
          },
          {
            "type": "HORIZONTAL_LINE",
            "clientObjectId": "entry_line",
            "points": [
              {
                "time": "2026-09-27T08:00:00.000Z",
                "price": 1.095
              }
            ],
            "style": {
              "color": "#2E7D32"
            },
            "key": "h-ray",
            "id": "66f000000000000000000b31",
            "isRaw": true,
            "timeRange": [1790035200000, 1790956800000]
          }
        ],
        "category": "analysis",
        "extra": {
          "happened": "[{\"type\":\"p\",\"children\":[{\"text\":\"Holding above \"},{\"type\":\"linked-text\",\"hoverIds\":[\"66f000000000000000000b41:0\"],\"children\":[{\"text\":\"support\",\"type\":\"text\",\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f61\"}],\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f71\"},{\"text\":\", targeting \"},{\"type\":\"linked-text\",\"hoverIds\":[\"66f000000000000000000b41:7\"],\"children\":[{\"text\":\"resistance\",\"type\":\"text\",\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f62\"}],\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f72\"},{\"text\":\".\"}],\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f60\"}]",
          "expected": "[{\"type\":\"p\",\"children\":[{\"text\":\"\"}],\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f80\"}]",
          "comments": "[{\"type\":\"p\",\"children\":[{\"text\":\"\"}],\"id\":\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f80\"}]",
          "direction": "bullish",
          "currency_pair": "EURUSD",
          "horizon": "SHORT",
          "userId": 3247779,
          "level": [
            {
              "title": "1st Support",
              "value": 1.08
            },
            {
              "title": "2nd Support",
              "value": 0
            },
            {
              "title": "Intermediate Support",
              "value": 0
            },
            {
              "title": "Downside Confirmation",
              "value": 0
            },
            {
              "title": "Upside Confirmation",
              "value": 0
            },
            {
              "title": "Intermediate Resistance",
              "value": 0
            },
            {
              "title": "2nd Resistance",
              "value": 0
            },
            {
              "title": "1st Resistance",
              "value": 1.12
            },
            {
              "title": "Pivot",
              "value": 1.1
            }
          ],
          "timeframe": "H1",
          "analysisType": {
            "expiry": 1,
            "title": "EURUSD bounce from support",
            "type": "bullish_bounce"
          },
          "status": "Pending",
          "intermediate": false
        },
        "roles": [],
        "private": false,
        "timeRange": {
          "x": [1790035200000, 1790956800000],
          "y": [1.078, 1.122]
        },
        "snapshot": null,
        "translationSource": "en",
        "translations": {},
        "createdAt": "2026-09-27T08:05:12.431Z",
        "updatedAt": "2026-09-27T08:05:12.431Z",
        "__v": 0
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

Errors#

These errors have no machine-readable code; branch on the HTTP status. The validation 400 names the parameter in detail; the ID format 400 has only status, statusCode and message. The 401 for a missing or unknown key has detail and a meta object; the 401 for a missing permission has only message.

Fix the request02

400Fix the request

Read the body:

List Analyses Request Validation validation error.: a query value is invalid, such as an upper-case direction, a status of Hit, or a page or limit that isn't a whole number. detail names the parameter.
Invalid community ID format or Invalid channel ID format: send 24-character IDs.

401Fix the request

The key is missing (Token is require.) or unknown (Token is wrong.), it's a personal key, or it lacks sendMessage (Your API key does not have permission to access this action). Send Authorization: Bearer <API_KEY> with a Community API key, and add Send Messages in Settings > Integration > API Keys.

Retry with backoff01

500Retry with backoff

The analyses could not be read. Retry the same request with exponential backoff.

{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "List Analyses Request Validation validation error.",
  "detail": {
    "direction": "Invalid enum value. Expected 'bullish' | 'bearish' | 'all', received 'BULLISH'"
  },
  "solution": "Check your query in request and try again"
}

Next step#

Get analysisGET/v1/analysis/{analysisId}Read one analysis with its channel post, using _id from the list.

Post a new card with Create analysis

List analyses

When to use this

01Authentication#

02Behaviour#

03Request#