Returning.AIDevelopers
v1

API reference / Chart Analysis

.md

Get analysis

Read one chart analysis by its ID, with its levels, drawings, status and the channel post that shows it.

Last updated 26 Sep 2026API v1

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

When to use this

  • Confirm a card you just created was saved with the levels and drawings you sent.
  • Check that an analysis is still Pending before you update it or add drawings.
  • Find the saved ID of a drawing by its clientObjectId.

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. Only read IDs that came from your own community's analyses. Personal API keys are not accepted here and return 401.

Request#

Path parameters#

analysisId#stringREQUIRED
The analysis ID from Create analysis (data.analysisId) or List analyses (_id).

Rule24 hex characters

Eg"66f000000000000000000b01"

Headers#

Authorization#stringREQUIRED
Community API key with sendMessage.

RuleBearer <API_KEY>

curl --request GET \
  --url https://api.returning.ai/v1/analysis/66f000000000000000000b01 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the analysis in data.analysis. What you sent at creation is in the shapes item whose key is analysis: levels and metadata exactly as submitted. Drawings follow in the same array. To find a drawing's saved id, match on your clientObjectId.

extra holds the values the card displays, such as status, the lower-case direction and the nine level values. message is the channel post that shows the card; after Delete analysis, the analysis itself returns 404.

status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.
message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Analysis fetched successfully"

data#objectALWAYS
Holds the analysis.

Eg{ ... }

analysis#objectALWAYS
The saved analysis. Fields not listed here are used by the app to draw the card.
_id#string
The analysis ID.
owner#object
Who posted it.
id#string
The sender's platform user ID.
serverId#string
Your community's ID.
topicId#string
The channel the card is posted in.
commentId#string
ID of the channel post that shows the card.
category#string
analysis for cards created through this API.
timeframe#string
Chart timeframe, such as H1.
shapes#object[]
The card and its drawings. The item with key analysis holds levels and metadata as you sent them. Every other item is a drawing, with your clientObjectId, type, points, style and its saved id.
extra#object
The card's summary values.
status#string
Pending for a new analysis. Only a Pending analysis can be updated or given more drawings.

RulePending, Active, Expired or Cancelled

direction#string
Direction in lower case.

Rulebullish or bearish

currency_pair#string
The symbol, in upper case.
level#object[]
Nine title and value pairs, from 1st Support to Pivot. Levels you didn't send have value 0.
analysisType#object
The card title in title, and the card type in type: bullish_breakout, bullish_bounce, bearish_bounce or bearish_breakout.
happened#string
The main scenario as formatted rich text, stored as a JSON string. alternativeText and comments are in expected and comments.
createdAt#string
When the analysis was created.
updatedAt#string
When the analysis last changed.
message#object
The channel post that shows the card, or null when it can't be found.
text#string
The card as the channel shows it, stored as a JSON string.
deleted#boolean
true when the post has been deleted.
{
  "status": "success",
  "statusCode": 200,
  "message": "Analysis fetched successfully",
  "data": {
    "analysis": {
      "_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,
      "message": {
        "_id": "66f000000000000000000b21",
        "text": "{\"type\":\"bullish_bounce\",\"title\":\"EURUSD bounce from support\",\"perference\":\"[{\\\"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\\\"}]\",\"alternativeScenario\":\"[{\\\"type\\\":\\\"p\\\",\\\"children\\\":[{\\\"text\\\":\\\"\\\"}],\\\"id\\\":\\\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f80\\\"}]\",\"comment\":\"[{\\\"type\\\":\\\"p\\\",\\\"children\\\":[{\\\"text\\\":\\\"\\\"}],\\\"id\\\":\\\"7c1e4f9a-2b6d-4e0a-9f3b-1a2c3d4e5f80\\\"}]\",\"category\":\"analysis\",\"currencyPair\":\"EURUSD\",\"timeframe\":\"H1\",\"typeTitle\":\"Bullish Bounce\",\"rValue\":1.12,\"pValue\":1.1,\"sValue\":1.08,\"content\":\"[{\\\"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\\\"}]\",\"fullCurrencyName\":\"EURUSD\",\"createdAt\":\"2026-09-27T08:05:12.431Z\",\"updatedAt\":\"2026-09-27T08:05:12.431Z\"}",
        "createdAt": "2026-09-27T08:05:12.431Z",
        "updatedAt": "2026-09-27T08:05:12.431Z",
        "deleted": false,
        "translations": {
          "primary": null,
          "extra_1": "EURUSD bounce from support",
          "extra_2": "{\"rawText\":\"Holding above [[support_main:support]], targeting [[resistance_main:resistance]].\",\"displayText\":\"Holding above support, targeting resistance.\",\"links\":[{\"objectId\":\"support_main\",\"displayText\":\"support\",\"startIndex\":14,\"endIndex\":21},{\"objectId\":\"resistance_main\",\"displayText\":\"resistance\",\"startIndex\":33,\"endIndex\":43}]}"
        },
        "serverId": "66f000000000000000000010",
        "topicId": "66f000000000000000000b11"
      }
    }
  }
}

Errors#

These errors have no machine-readable code; branch on the HTTP status. The 401 for a missing or unknown key has detail and a meta object; the 401 for a missing permission has only message. Other errors carry status, statusCode and message.

Fix the request02

400Fix the request
analysisId isn't a valid ID. Send the 24-character ID from Create analysis or List analyses.
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.

Fix the data01

404Fix the data
No analysis has this ID, or it was deleted. List the channel's analyses to find the right ID.

Retry with backoff01

500Retry with backoff
The analysis could not be read. Retry the same request with exponential backoff.
{
  "status": "fail",
  "statusCode": 400,
  "message": "Invalid analysis ID format"
}

Next step#

Update analysisPATCH/v1/analysis/{analysisId}Change the title, scenarios, expiry, direction or drawings while the analysis is Pending.