> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Copy instructions

> GET /v1/copy-trading/instructions and GET /v1/copy-trading/instructions/item: the copy instructions of your instance, newest first, by user and status, and one instruction by id.

The [copy instructions](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#the-instruction) CabalSpy ID made for your users. New instructions are pushed as the `copy_trade.instruction` [webhook](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#copy-trading-events) and on the [stream](https://docs.cabalspy.xyz/cabalspy-id/copy-trading-stream.md); use these endpoints to catch up after downtime, to show a user's copy history, or to poll when you have neither.

A key only reaches the instructions of its own instance: those made for users whose copying your instance switched on.

## List instructions

`GET /v1/copy-trading/instructions`

Instructions newest first, for all your users or one.

### Query Parameters

**external\_id** `string`

Only instructions of this user, by your own user id. Alternatively pass csid\_id. Without either, instructions of all your users.

**csid\_id** `string`

Only instructions of this user, by CabalSpy ID.

**status** `string`

Only instructions with this status: `pending`, `executed`, `failed`, `skipped` or `expired`. `pending` means not reported and not yet expired, `expired` means not reported and older than 120 seconds.

**limit** `integer` (default: 50)

Instructions per page, 1 to 100.

**cursor** `string`

Cursor for the next page, the pagination.next\_cursor from the previous response.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/copy-trading/instructions?status=pending&limit=100" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

params = {"external_id": "user_8412", "limit": 50}
while True:
    r = requests.get("https://api-id.cabalspy.xyz/v1/copy-trading/instructions", params=params,
                     headers={"Authorization": "Bearer YOUR_KEY"}).json()
    for i in r["data"]:
        a = i["action"]
        print(i["created_at"], a["side"], a["symbol"], a["amount_usd"] or f'{a["sell_percent"]}%', i["status"])
    if not r["pagination"]["has_more"]:
        break
    params["cursor"] = r["pagination"]["next_cursor"]
```

```javascript JavaScript theme={null}
// after a restart: everything still waiting for you
const res = await fetch("https://api-id.cabalspy.xyz/v1/copy-trading/instructions?status=pending&limit=100", {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
data.forEach(i => queueCopy(i));
```

### Response

**data** `array`

[Instruction objects](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#the-instruction), newest first. `external_id` is not part of them here; match the user by `csid_id`.

**pagination** `object`

limit, has\_more and next\_cursor (pass it as cursor; null on the last page).

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "id": "9d4b2f6e-1c3a-5e7f-8a9b-0c1d2e3f4a5b",
      "type": "copy_instruction",
      "status": "executed",
      "created_at": "2026-11-01T18:02:11Z",
      "expires_at": "2026-11-01T18:04:11Z",
      "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
      "trader": {
        "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09",
        "username": "MazeCCC",
        "name": "Maze",
        "image_url": "https://pbs.twimg.com/profile_images/1/maze_normal.jpg",
        "kol": true,
        "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
      },
      "action": {
        "blockchain": "solana",
        "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
        "symbol": "CPT",
        "name": "Copycat",
        "logo": "https://...",
        "side": "buy",
        "amount_usd": 20.0,
        "amount_native": 0.133333333,
        "currency": "SOL",
        "sell_percent": null,
        "price_usd": 0.15,
        "max_price_usd": 0.1545,
        "min_price_usd": null,
        "slippage_bps": 300
      },
      "source_trade": { "side": "buy", "label": "new", "amount_usd": 150.0, "price_usd": 0.15, "...": "the trader's trade" },
      "settings": { "enabled": true, "mode": "fixed_usd", "amount_usd": 25.0, "percent": 100.0, "max_usd": 20.0, "sides": "both", "slippage_bps": 300, "updated_at": "2026-11-01T17:58:40Z" },
      "links": { "token": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "terminal": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "profile": "https://id.cabalspy.xyz/u/MazeCCC" },
      "tx_signature": "4hXt9...",
      "executed_amount_usd": 19.8,
      "note": null,
      "updated_at": "2026-11-01T18:02:19Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-11-01T18:05:00Z"
  }
}
```

### Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | invalid\_parameter | status, limit, cursor or csid\_id invalid. For status, `allowed` lists the accepted values. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | [consent\_required](https://docs.cabalspy.xyz/cabalspy-id/errors.md#consent_required) | The user you filtered by has not granted your app the scope `trade_feed`, or is beyond your plan's user limit. |
| 404 | [platform\_user\_not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#platform_user_not_found) | No platform user with this external\_id. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

## Get one instruction

`GET /v1/copy-trading/instructions/item`

One instruction by id, as an [instruction object](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#the-instruction), with its current status and what you reported.

### Query Parameters

**id** `string` *required*

The instruction id.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/copy-trading/instructions/item?id=9d4b2f6e-1c3a-5e7f-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

r = requests.get("https://api-id.cabalspy.xyz/v1/copy-trading/instructions/item",
                 params={"id": "9d4b2f6e-1c3a-5e7f-8a9b-0c1d2e3f4a5b"},
                 headers={"Authorization": "Bearer YOUR_KEY"})
i = r.json()["data"]
print(i["status"], i["tx_signature"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/copy-trading/instructions/item?id=9d4b2f6e-1c3a-5e7f-8a9b-0c1d2e3f4a5b", {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
console.log(data.status, data.action.side, data.action.mint);
```

### Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | id is missing. |
| 400 | invalid\_parameter | id is not a valid id. |
| 404 | [not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#not_found) | No copy instruction with this id for your instance. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.