Last updated

Pagination

Most of our API endpoints support Cursor-based pagination.

Cursors are like pointers.

Pointers point at things: they reference a specific iota, a place in the list where your last request left off. They help avoid loading an entire set just to give you a slice.

A cursor-paginated method returns two things: a portion of the total set of results, and a cursor that points to the next portion of the results.

How Pagination Works

  • Cursor-paginated methods accept Cursor, AscendingOrder and Limit parameters.

  • If you don't pass a cursor parameter, but do pass a limit parameter, the default value retrieves the first portion (or "page") of results.

  • If you set AscendingOrder=false, you will receive results in descending order (i.e. the data will start from the end).

  • Paginated responses include a top-level Pagination object that includes a next_cursor when there are additional results to be retrieved, and a prev_cursor when there are previous results to be retrieved.

  • On your next call to the same method, set the cursor parameter equal to the next_cursor value you received on the last request to retrieve the next portion of the collection.

  • You will receive the cursor ASCII UrlEncoded, so be sure to pass it back UrlDecoded.

  • An empty, null, or non-existent next_cursor in the response indicates no further results.

  • An empty, null, or non-existent prev_cursor in the response indicates no previous results.

  • An empty, null, or non-existent Pagination in the response indicates no further or previous results.

  • The limit parameter sets a maximum number of results to return per call.

  • The limit parameter maximum is 1000. It is subject to change and may vary per method.

  • It's possible to receive fewer results than your specified limit, even when there are additional results to retrieve. Avoid the temptation to check the size of results against the limit to conclude the results have been completely returned. Instead, check the next_cursor value in the Metaobject to make sure that it's empty, null, or non-existent.

  • Cursors expire and are meant to be used within a reasonable amount of time. You should have no trouble pausing between rate limiting windows, but do not persist cursors for more than one hour or they may be rejected.

Paginated response properties:

Field NameTypeRequiredComments
PaginationOptionalJSON
Field NameTypeRequiredComments
prev_cursorstringOptionalThe previous Pagination Cursor
next_cursorstringOptionalThe next Pagination Cursor

Paginated request parameters:

Field NameTypeRequiredComments
CursorstringOptionalThe Cursor you received in the the previous resultset.
LimitintegerOptionalResult size limit. We will enforce a max size limit for all endpoints. Default is 1000.
AscendingOrderbooleanOptionalSet to FALSE if you want to get the newest results first. Default is TRUE (oldest results first).

Example where we request a list of historical orders and limit the response to 2 items:

Request

curl --location 'https://api4-general.collective2.com/Strategies/GetStrategyHistoricalOrders?StrategyId=110388479&Limit=2' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \

Response

{
    "Results": [
        {
            "OrderStatus": "2",
            "FilledQuantity": 1,
            "AvgFillPrice": 15674,
            "PostedDate": "2023-07-25T12:39:52",
            "SignalType": 1,
            "Id": 145318990,
            "StrategyId": 110388479,
            "StrategyName": "Senor Premium Three",
            "SignalId": 145318990,
            "OrderType": "1",
            "Side": "1",
            "OpenClose": "C",
            "OrderQuantity": 1,
            "TIF": "0",
            "C2Symbol": {
                "FullSymbol": "@MNQU3",
                "SymbolType": "future",
                "Underlying": "@MNQ",
                "Description": "MICRO E-MINI NASDAQ 100"
            },
            "ExchangeSymbol": {
                "Symbol": "MNQ",
                "Currency": "USD",
                "SecurityExchange": "XCME",
                "SecurityType": "FUT",
                "MaturityMonthYear": "202309",
                "PriceMultiplier": 1
            }
        },
        {
            "OrderStatus": "2",
            "FilledQuantity": 2,
            "AvgFillPrice": 349.13,
            "PostedDate": "2023-07-25T12:39:51",
            "SignalType": 1,
            "Id": 145318989,
            "StrategyId": 110388479,
            "StrategyName": "Senor Premium Three",
            "SignalId": 145318989,
            "OrderType": "1",
            "Side": "2",
            "OpenClose": "C",
            "OrderQuantity": 2,
            "TIF": "0",
            "C2Symbol": {
                "FullSymbol": "MSFT",
                "SymbolType": "stock",
                "Description": "MSFT trades on > 1 exchange"
            },
            "ExchangeSymbol": {
                "Symbol": "MSFT",
                "Currency": "USD",
                "SecurityExchange": "DEFAULT",
                "SecurityType": "CS",
                "PriceMultiplier": 1
            }
        }
    ],
    "Pagination": {
        "next_cursor": "CrmfVLqva1gNWKZnEZl5pLY1QbZkRIzdW0GKxt1dgmc9nISZmQfGdsjCIgm6WzjHJrPp%2FuU5Yu9pdzN0wBBhBX9QqTY4SicIchWFUPOYY%2Fc%3D"
    },   
    "ResponseStatus": {
        "ErrorCode": "200"
    }
}

Now we want to request the next 2 orders:

Request

curl --location 'https://api4-general.collective2.com/Strategies/GetStrategyHistoricalOrders?StrategyId=110388479&Cursor=CrmfVLqva1gNWKZnEZl5pLY1QbZkRIzdW0GKxt1dgmc9nISZmQfGdsjCIgm6WzjHJrPp%2FuU5Yu9pdzN0wBBhBX9QqTY4SicIchWFUPOYY%2Fc%3D&Limit=2' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \

Response

{
    "Results": [
        {
            "OrderStatus": "2",
            "FilledQuantity": 1,
            "AvgFillPrice": 15616.5,
            "PostedDate": "2023-07-25T09:40:48",
            "SignalType": 1,
            "Id": 145315427,
            "StrategyId": 110388479,
            "StrategyName": "Senor Premium Three",
            "SignalId": 145315427,
            "OrderType": "1",
            "Side": "2",
            "OpenClose": "O",
            "OrderQuantity": 1,
            "TIF": "0",
            "C2Symbol": {
                "FullSymbol": "@MNQU3",
                "SymbolType": "future",
                "Underlying": "@MNQ",
                "Description": "MICRO E-MINI NASDAQ 100"
            },
            "ExchangeSymbol": {
                "Symbol": "MNQ",
                "Currency": "USD",
                "SecurityExchange": "XCME",
                "SecurityType": "FUT",
                "MaturityMonthYear": "202309",
                "PriceMultiplier": 1
            }
        },
        {
            "OrderStatus": "2",
            "FilledQuantity": 2,
            "AvgFillPrice": 15610.5,
            "PostedDate": "2023-07-25T09:40:04",
            "SignalType": 1,
            "Id": 145315397,
            "StrategyId": 110388479,
            "StrategyName": "Senor Premium Three",
            "SignalId": 145315397,
            "OrderType": "2",
            "Side": "2",
            "OpenClose": "C",
            "OrderQuantity": 2,
            "Limit": 1.25,
            "TIF": "1",
            "C2Symbol": {
                "FullSymbol": "@MNQU3",
                "SymbolType": "future",
                "Underlying": "@MNQ",
                "Description": "MICRO E-MINI NASDAQ 100"
            },
            "ExchangeSymbol": {
                "Symbol": "MNQ",
                "Currency": "USD",
                "SecurityExchange": "XCME",
                "SecurityType": "FUT",
                "MaturityMonthYear": "202309",
                "PriceMultiplier": 1
            }
        }
    ],
    "Pagination": {
        "prev_cursor": "CrmfVLqva1gNWKZnEZl5pFudrj6M9nJO4i1voJrPYliQBwE7crnkrdqItRcuX7k%2F8VR8XxYoKrtmtopPnT2YVl7AOLZMN%2FILgTnVNXMQGG4%3D",
        "next_cursor": "CrmfVLqva1gNWKZnEZl5pFudrj6M9nJO4i1voJrPYliQBwE7crnkrdqItRcuX7k%2F6b8SMaXM3g7xoze2Usx%2FSz6Qkn2oB7b4Y6iLRRC3czs%3D"
    },
    "ResponseStatus": {
        "ErrorCode": "200"
    }
}