# List analyses List the chart analyses in one channel, newest first, with optional filters for status, direction and timeframe. - Endpoint: `GET https://api.returning.ai/v1/analysis/communities/{communityId}/channels/{channelId}` - 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: live, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/chart-analysis/list-analyses ## 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. **Instead:** Use [Get analysis](https://docs.returning.ai/api-reference/chart-analysis/get-analysis.md) instead when you already have the analysis ID and also want its channel post. ## 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. 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 | Name | Type | Required | Description | | --- | --- | --- | --- | | `communityId` | `string` | Yes | Your community's ID. (24 hex characters) | | `channelId` | `string` | Yes | The chart channel to list. A channel with no analyses, including a channel without charts, returns an empty list. (24 hex characters) | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `status` | `string` | No | Only analyses with this status. `all`, or leaving it out, returns every status. (`Pending`, `Active`, `Expired`, `Cancelled` or `all`) | | `direction` | `string` | No | Only analyses with this direction. Lower case here, unlike `metadata.direction` on Create analysis. (`bullish`, `bearish` or `all`) | | `timeframe` | `string` | No | Only analyses on this chart timeframe. (`M1`, `M5`, `M15`, `M30`, `H1`, `H2`, `H4`, `D`, `W`, `M` or `all`) | | `sortBy` | `string` | No | What to sort by. (`createdAt`, `updatedAt` or `status`; default `createdAt`) | | `sortOrder` | `string` | No | Sort direction. `desc`, the default, puts the newest first. (`desc` or `asc`) | | `page` | `integer` | No | Page number, starting at 1. (Whole number, 1 or more; default 1) | | `limit` | `integer` | No | Analyses per page. (Default 20) | ### 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/communities/66f000000000000000000010/channels/66f000000000000000000b11?status=Pending&page=1&limit=20' \ --header 'Authorization: Bearer ' ``` ## 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. ### 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 | This page of analyses and the paging totals. | | `data.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. | | `data.analyses._id` | `string` | - | The analysis ID. Use it with Get, Update, Append drawings and Delete. | | `data.analyses.shapes` | `object[]` | - | The card (the item with `key` `analysis`, holding `levels` and `metadata`) followed by its drawings. | | `data.analyses.extra` | `object` | - | Summary values, including `status`, the lower-case `direction`, `currency_pair` and `analysisType.title`. | | `data.analyses.timeframe` | `string` | - | Chart timeframe. | | `data.analyses.createdAt` | `string` | - | When the analysis was created. (Date-time) | | `data.analyses.updatedAt` | `string` | - | When the analysis last changed. (Date-time) | | `data.pagination` | `object` | always | Paging totals for everything that matches. | | `data.pagination.page` | `integer` | - | The page you asked for. | | `data.pagination.limit` | `integer` | - | The page size used. | | `data.pagination.total` | `integer` | - | Analyses that match, across all pages. | | `data.pagination.totalPages` | `integer` | - | Pages at this `limit`. `0` when nothing matches. | | `data.pagination.hasNextPage` | `boolean` | - | `true` when a later page has analyses. | | `data.pagination.hasPrevPage` | `boolean` | - | `true` when `page` is above 1. | ### Example response (200) ```json { "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 request | Status | Code | What to do | | --- | --- | --- | | 400 | - | 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. | | 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. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | - | The analyses 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. New analyses push older ones down while you page, so sort by `createdAt` ascending if you copy a whole channel. ## Next step - [Get analysis](https://docs.returning.ai/api-reference/chart-analysis/get-analysis.md): `GET /v1/analysis/{analysisId}`. Read one analysis with its channel post, using `_id` from the list. - [Post a new card with Create analysis](https://docs.returning.ai/api-reference/chart-analysis/create-analysis.md): `POST /v1/analysis/{communityId}/channels/{channelId}`. Post only when the list shows your analysis isn't there yet.