# Get analysis Read one chart analysis by its ID, with its levels, drawings, status and the channel post that shows it. - Endpoint: `GET https://api.returning.ai/v1/analysis/{analysisId}` - Section: Community / Chart analysis - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `sendMessage` (Shown in the dashboard as "Send Messages") - Retries: Read-only; exact retries are safe - Guide: hand-written - Verified: code, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/chart-analysis/get-analysis ## 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`. **Instead:** Use [List analyses](https://docs.returning.ai/api-reference/chart-analysis/list-analyses.md) instead to find analyses in a channel when you don't have the ID. ## Authentication - Header: `Authorization: Bearer ` - Permission: `sendMessage` 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 | Name | Type | Required | Description | | --- | --- | --- | --- | | `analysisId` | `string` | Yes | The analysis ID from Create analysis (`data.analysisId`) or List analyses (`_id`). (24 hex characters) | ### Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `sendMessage`. (`Bearer `) | ### Example request ```bash curl --request GET \ --url https://api.returning.ai/v1/analysis/66f000000000000000000b01 \ --header 'Authorization: Bearer ' ``` ## 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`. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `status` | `string` | always | Result of the request. (`success`) | | `statusCode` | `integer` | always | The HTTP status, repeated. | | `message` | `string` | always | Human-readable summary. Do not branch on it. | | `data` | `object` | always | Holds the analysis. | | `data.analysis` | `object` | always | The saved analysis. Fields not listed here are used by the app to draw the card. | | `data.analysis._id` | `string` | - | The analysis ID. | | `data.analysis.owner` | `object` | - | Who posted it. | | `data.analysis.owner.id` | `string` | - | The sender's platform user ID. | | `data.analysis.serverId` | `string` | - | Your community's ID. | | `data.analysis.topicId` | `string` | - | The channel the card is posted in. | | `data.analysis.commentId` | `string` | - | ID of the channel post that shows the card. | | `data.analysis.category` | `string` | - | `analysis` for cards created through this API. | | `data.analysis.timeframe` | `string` | - | Chart timeframe, such as `H1`. | | `data.analysis.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`. | | `data.analysis.extra` | `object` | - | The card's summary values. | | `data.analysis.extra.status` | `string` | - | `Pending` for a new analysis. Only a `Pending` analysis can be updated or given more drawings. (`Pending`, `Active`, `Expired` or `Cancelled`) | | `data.analysis.extra.direction` | `string` | - | Direction in lower case. (`bullish` or `bearish`) | | `data.analysis.extra.currency_pair` | `string` | - | The symbol, in upper case. | | `data.analysis.extra.level` | `object[]` | - | Nine `title` and `value` pairs, from `1st Support` to `Pivot`. Levels you didn't send have `value` `0`. | | `data.analysis.extra.analysisType` | `object` | - | The card title in `title`, and the card type in `type`: `bullish_breakout`, `bullish_bounce`, `bearish_bounce` or `bearish_breakout`. | | `data.analysis.extra.happened` | `string` | - | The main scenario as formatted rich text, stored as a JSON string. `alternativeText` and `comments` are in `expected` and `comments`. | | `data.analysis.createdAt` | `string` | - | When the analysis was created. | | `data.analysis.updatedAt` | `string` | - | When the analysis last changed. | | `data.analysis.message` | `object` | - | The channel post that shows the card, or `null` when it can't be found. | | `data.analysis.message.text` | `string` | - | The card as the channel shows it, stored as a JSON string. | | `data.analysis.message.deleted` | `boolean` | - | `true` when the post has been deleted. | ### Example response (200) ```json { "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 request | Status | Code | What to do | | --- | --- | --- | | 400 | - | `analysisId` isn't a valid ID. Send the 24-character ID from Create analysis or List analyses. | | 401 | - | 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 ` with a Community API key, and add Send Messages in Settings > Integration > API Keys. | ### Fix the data | Status | Code | What to do | | --- | --- | --- | | 404 | - | No analysis has this ID, or it was deleted. List the channel's analyses to find the right ID. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | - | The analysis could not be read. Retry the same request with exponential backoff. | **Retries:** This endpoint is read-only. Retrying the exact same request is safe after a network error or a `500`; use bounded exponential backoff. Don't retry a `404` without changing the ID. ## Next step - [Update analysis](https://docs.returning.ai/api-reference/chart-analysis/update-analysis.md): `PATCH /v1/analysis/{analysisId}`. Change the title, scenarios, expiry, direction or drawings while the analysis is `Pending`. - [Append drawings](https://docs.returning.ai/api-reference/chart-analysis/append-drawings.md): `POST /v1/analysis/{analysisId}/drawings`. Add drawings without replacing the ones already on the card.