# post

## Overview

This endpoint is used for initiating ReadSessions for tables, uploads, and query results. A ReadSession can consist of one or more read streams, which are subsequently consumed via the [getStream](/api/rest-api/readsessions/get.md) endpoint.

ReadSessions expire after 6 hours.

{% hint style="warning" %}
When creating a read session for an unreleased table, note that a stream will be returned for each upload on the table, as well as (potentially) for the previous version of the table. 

It is possible for these streams to have different schema, and it is the responsibility of the stream consumer(s) to handle accordingly.
{% endhint %}

## HTTP Request

```http
POST /tables/:tableReference/readSessions
POST /uploads/:uploadReference/readSessions
POST /queries/:queryId/readSessions
```

{% hint style="info" %}
This endpoint extends the [general API structure](/api/rest-api/general-structure.md)
{% endhint %}

## Request body

Provide a JSON object with information about the dataset.

<table><thead><tr><th width="238">Property name</th><th>Type</th><th width="341.3333333333333">Description</th></tr></thead><tbody><tr><td><strong>format</strong></td><td><strong>string</strong></td><td><strong>Optional, default "arrow".</strong> The format of the stream results. Must be one of <code>"arrow"</code>, <code>"jsonl"</code>, or <code>"csv"</code>. <br><br>If <strong>arrow</strong>, each stream will be encoded the Arrow IPC Stream binary specification.<br><br>If <strong>jsonl</strong>, each stream will be encoded as newline-delimited JSON, with each JSON record representing a single row.<br><br>If <strong>csv</strong>, each stream will be encoded as a CSV, including a header.</td></tr><tr><td><strong>maxResults</strong></td><td><strong>string</strong></td><td><strong>Optional</strong>. Maximum number of rows to return.</td></tr><tr><td><strong>selectedVariables</strong></td><td><strong>string[]</strong></td><td><p><strong>Optional</strong>. A comma separated list of the variables to return, case insensitive. The order of variables in this list will determine the order of values in the response.</p><p></p><p>If not specified, all variables belonging to the table will be returned.</p></td></tr><tr><td><strong>requestedStreamCount</strong></td><td><strong>integer</strong></td><td><strong>Optional, default 1.</strong> The requested number of streams to return. More streams may allow for higher throughput via parallelization.<br><br>There is no guarantee that the number of streams returned will be equivalent to the <code>requestedStreamCount</code>. If a table is unreleased, at minimum a stream will be returned for each upload on the unreleased table. For other tables, uploads, and query results, the requested stream count will be treated as a maximum, but in certain cases fewer streams may be returned than requested, particularly for smaller tables.</td></tr><tr><td><strong>allowAnonymousAccess</strong></td><td><strong>bool</strong></td><td><strong>Optional, default false.</strong> Whether to allow anonymous download to any client with the stream id. Useful for when an API consumer may want to return a stream to another client without that client possessing Redivis API credentials. <br><br>Extreme care must be taken when using this approach, to ensure that stream ids are not inadvertently leaked to inappropriate actors.</td></tr></tbody></table>

## Authorization

Data access to all tables referenced by the query is required. If a table's data is not public, your access token must have one of the following scopes:

* data.data
* data.edit

[Learn more about authorization.](/api/rest-api/authorization.md)

## Response body

```json
{
  "kind": "readSession",
  "streams": [
    {
      "kind": "readStream",
      "id": str,
      "format": str,     // One of "arrow", "csv", "jsonl"
      "expiresAt": int   // Expiration timestamp, in millisconds since the epoch
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.redivis.com/api/rest-api/readsessions/post.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.