<divclass="dev_page_bread_crumbs"><ulclass="breadcrumb clearfix"><li><ahref="/api">API</a></li><iclass="icon icon-breadcrumb-divider"></i><li><ahref="/api/offsets">Pagination in the API</a></li></ul></div>
<h1id="dev_page_title">Pagination in the API</h1>
<divid="dev_page_content"><!-- scroll_nav -->
<p>Lots of Telegram API methods provide access to potentially large lists of objects, which requires pagination.</p>
<p>In order to fetch only relevant subset of results for each request there is a number of available input parameters. Here is a list in order how they are applied in API.</p>
<p>Typically, results are returned in reverse chronological order with descending object ID values.</p>
<p>A limit on the number of objects to be returned, typically between 1 and 100. When 0 is provided the limit will often default to an intermediate value like ~20.</p>
<p>For a few methods with mostly static data this parameter allows to skip <code>offset</code> elements from the beginning of list; negative values are ignored.</p>
<p>For most methods where results are real-time data (e.g. any chat history) <code>offset</code> value is not passed directly. Instead it is calculated from the passed <code>offset_id</code> and <code>add_offset</code> parameter values as <code>offsetFromID(offset_id) + add_offset</code>, where <code>offsetFromID(offset_id)</code> is a number of results from the beginning of list up to the result with ID <code>offset_id</code>, inclusive.</p>
<p>Sample use cases:</p>
<ul>
<li>
<p>Loading 20 messages, older than message with ID <code>MSGID</code>:</p>
<p>To further reduce the result subset, there is a mechanism to avoid fetching data if the resulting list hasn't changed from the one stored on client, similar to <ahref="https://en.wikipedia.org/wiki/HTTP_ETag">ETag</a>.</p>
<p>When the client has cached results for API request, it can calculate the <code>hash</code> value for it by taking the result IDs (message IDs or other fields with name <code>id</code>) and using them to compute a 64-bit hash with the following algorithm:</p>
<pre><code># Here, ^ indicates a bitwise XOR
hash = 0
for id in ids:
hash = hash ^ (id >> 21)
hash = hash ^ (id << 35)
hash = hash ^ (id >> 4)
hash = hash + id</code></pre>
<p>In some cases, the result container already has a <code>hash</code> field, that can be used instead.</p>
<p>When the client passes a correct value, the API will return one of <code>*NotModified</code> constructors, e.g. <ahref="/constructor/messages.messagesNotModified">messages.messagesNotModified</a> instead of the actual results.</p>
<li><ahref="/method/messages.getHistory">messages.getHistory</a> supports all result navigation parameters including message ID hashes and except filters</li>
<li><ahref="/method/channels.getParticipants">channels.getParticipants</a> supports simple navigation using <strong>limit</strong> and <strong>offset</strong>, along with filtering and <code>hash</code> reducing using the user IDs of returned participants</li>
</ul></div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
