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

# Get stored relationship tuples

> The Read API returns the tuples from a certain store that match a query filter specified in the body of the request. 
The API doesn't guarantee order by any field. 
It is different from the `/stores/{store_id}/expand` API in that it only returns relationship tuples that are stored in the system and satisfy the query. 
In the body:
1. `tuple_key` is optional. If not specified, it returns all tuples in the store.
2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can be a full object (e.g., `type:object_id`) or type only (e.g., `type:`).
3. `tuple_key.user` is mandatory if tuple_key is specified in the case the `tuple_key.object` is a type only. If tuple_key.user is specified, it needs to be a full object (e.g., `type:user_id`).

## Examples

### Query for all objects in a type definition

To query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of
```json
{
 "tuple_key": {
     "user": "user:bob",
     "relation": "reader",
     "object": "document:"
  }
}
```
The API returns tuples and a continuation token, similar to:
```json
{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "reader",
        "object": "document:2021-budget"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
```
This means that `user:bob` has a `reader` relationship with 1 document `document:2021-budget`. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store.
The continuation token is empty if there are no more tuples to query.

### Query for all stored relationship tuples that have a particular relation and object

To query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of 
```json
{
  "tuple_key": {
     "object": "document:2021-budget",
     "relation": "reader"
   }
}
```
The API returns something similar to: 
```json
{
  "tuples": [
    {
      "key": {
        "user": "user:bob",
        "relation": "reader",
        "object": "document:2021-budget"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
```
This means that `document:2021-budget` has 1 `reader` (`user:bob`).  Note that, even if the model said that all `writers` are also `readers`, the API does not return writers such as `user:anne` because it only returns tuples and does not evaluate them.

### Query for all users with all relationships for a particular document

To query for all users that have any relationship with `document:2021-budget`, call read API with body of 
```json
{
  "tuple_key": {
      "object": "document:2021-budget"
   }
}
```
The API returns something similar to:
```json
{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "writer",
        "object": "document:2021-budget"
      },
      "timestamp": "2021-10-05T13:42:12.356Z"
    },
    {
      "key": {
        "user": "user:bob",
        "relation": "reader",
        "object": "document:2021-budget"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}
```
This means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).




## OpenAPI

````yaml https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json post /stores/{store_id}/read
openapi: 3.0.3
info:
  contact:
    email: community@openfga.dev
    name: OpenFGA
    url: https://openfga.dev
  description: >-
    A high performance and flexible authorization/permission engine built for
    developers and inspired by Google Zanzibar.
  license:
    name: Apache-2.0
    url: https://github.com/openfga/openfga/blob/main/LICENSE
  title: OpenFGA
  version: 1.x
servers: []
security: []
tags:
  - name: AuthZenService
  - name: OpenFGAService
paths:
  /stores/{store_id}/read:
    post:
      tags:
        - Relationship Tuples
      summary: Get stored relationship tuples
      description: >
        The Read API returns the tuples from a certain store that match a query
        filter specified in the body of the request. 

        The API doesn't guarantee order by any field. 

        It is different from the `/stores/{store_id}/expand` API in that it only
        returns relationship tuples that are stored in the system and satisfy
        the query. 

        In the body:

        1. `tuple_key` is optional. If not specified, it returns all tuples in
        the store.

        2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can
        be a full object (e.g., `type:object_id`) or type only (e.g., `type:`).

        3. `tuple_key.user` is mandatory if tuple_key is specified in the case
        the `tuple_key.object` is a type only. If tuple_key.user is specified,
        it needs to be a full object (e.g., `type:user_id`).


        ## Examples


        ### Query for all objects in a type definition


        To query for all objects that `user:bob` has `reader` relationship in
        the `document` type definition, call read API with body of

        ```json

        {
         "tuple_key": {
             "user": "user:bob",
             "relation": "reader",
             "object": "document:"
          }
        }

        ```

        The API returns tuples and a continuation token, similar to:

        ```json

        {
          "tuples": [
            {
              "key": {
                "user": "user:bob",
                "relation": "reader",
                "object": "document:2021-budget"
              },
              "timestamp": "2021-10-06T15:32:11.128Z"
            }
          ],
          "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
        }

        ```

        This means that `user:bob` has a `reader` relationship with 1 document
        `document:2021-budget`. Note that this API, unlike the List Objects API,
        does not evaluate the tuples in the store.

        The continuation token is empty if there are no more tuples to query.


        ### Query for all stored relationship tuples that have a particular
        relation and object


        To query for all users that have `reader` relationship with
        `document:2021-budget`, call read API with body of 

        ```json

        {
          "tuple_key": {
             "object": "document:2021-budget",
             "relation": "reader"
           }
        }

        ```

        The API returns something similar to: 

        ```json

        {
          "tuples": [
            {
              "key": {
                "user": "user:bob",
                "relation": "reader",
                "object": "document:2021-budget"
              },
              "timestamp": "2021-10-06T15:32:11.128Z"
            }
          ],
          "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
        }

        ```

        This means that `document:2021-budget` has 1 `reader` (`user:bob`). 
        Note that, even if the model said that all `writers` are also `readers`,
        the API does not return writers such as `user:anne` because it only
        returns tuples and does not evaluate them.


        ### Query for all users with all relationships for a particular document


        To query for all users that have any relationship with
        `document:2021-budget`, call read API with body of 

        ```json

        {
          "tuple_key": {
              "object": "document:2021-budget"
           }
        }

        ```

        The API returns something similar to:

        ```json

        {
          "tuples": [
            {
              "key": {
                "user": "user:anne",
                "relation": "writer",
                "object": "document:2021-budget"
              },
              "timestamp": "2021-10-05T13:42:12.356Z"
            },
            {
              "key": {
                "user": "user:bob",
                "relation": "reader",
                "object": "document:2021-budget"
              },
              "timestamp": "2021-10-06T15:32:11.128Z"
            }
          ],
          "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
        }

        ```

        This means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1
        `writer` (`user:anne`).
      operationId: Read
      parameters:
        - in: path
          name: store_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
          description: A successful response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessageResponse'
          description: Request failed due to invalid input.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
          description: Not authenticated.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathUnknownErrorMessageResponse'
          description: Request failed due to incorrect path.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbortedMessageResponse'
          description: Request was aborted due a transaction conflict.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentMessageResponse'
          description: Request timed out due to excessive request throttling.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorMessageResponse'
          description: Request failed due to internal server error.
      x-codeSamples:
        - lang: node
          label: Node.js
          source: >-
            const { OpenFgaClient, ConsistencyPreference } =
            require('@openfga/sdk');


            const fgaClient = new OpenFgaClient({
              apiUrl: process.env.FGA_API_URL,
              storeId: process.env.FGA_STORE_ID,
            });


            async function main() {
                const body = {
                  "user": "user:anne",
                  "relation": "reader",
                  "object": "document:budget"
                };
                const options = {
                  "pageSize": 20
                };
                const response = await fgaClient.read(body, options);
            }


            main().catch((error) => {
                console.error(error);
                process.exitCode = 1;
            });
        - lang: go
          label: Go
          source: |-
            package main

            import (
                "context"
                "os"

                . "github.com/openfga/go-sdk/client"
            )

            func main() {
                fgaClient, err := NewSdkClient(&ClientConfiguration{
                    ApiUrl: os.Getenv("FGA_API_URL"),
                    StoreId: os.Getenv("FGA_STORE_ID"),
                })
                if err != nil {
                    panic(err)
                }
                
                pageSize := int32(20)
                user := "user:anne"
                relation := "reader"
                object := "document:budget"
                body := ClientReadRequest{
                    User: &user,
                    Relation: &relation,
                    Object: &object,
                }
                options := ClientReadOptions{
                    PageSize: &pageSize,
                }
                response, err := fgaClient.Read(context.Background()).Body(body).Options(options).Execute()
                if err != nil {
                    panic(err)
                }
                _ = response
            }
        - lang: dotnet
          label: .NET
          source: |-
            using System.Collections.Generic;
            using OpenFga.Sdk.Client;
            using OpenFga.Sdk.Client.Model;
            using OpenFga.Sdk.Model;
            using Environment = System.Environment;

            var fgaClient = new OpenFgaClient(new ClientConfiguration() {
              ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
              StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            });

            var body = new ClientReadRequest {
                User = "user:anne",
                Relation = "reader",
                Object = "document:budget",
            };
            var options = new ClientReadOptions {
                PageSize = 20,
            };
            var response = await fgaClient.Read(body, options);
        - lang: python
          label: Python
          source: |-
            import asyncio
            import os
            from openfga_sdk.client import OpenFgaClient, ClientConfiguration
            from openfga_sdk import ReadRequestTupleKey

            async def main():
                configuration = ClientConfiguration(
                    api_url=os.environ.get("FGA_API_URL"),
                    store_id=os.environ.get("FGA_STORE_ID"),
                )
                async with OpenFgaClient(configuration) as fga_client:
                    body = ReadRequestTupleKey(
                        user="user:anne",
                        relation="reader",
                        object="document:budget",
                    )
                    options = {"page_size": 20}
                    response = await fga_client.read(body=body, options=options)

            asyncio.run(main())
        - lang: java
          label: Java
          source: |-
            import dev.openfga.sdk.api.client.OpenFgaClient;
            import dev.openfga.sdk.api.configuration.ClientConfiguration;
            import dev.openfga.sdk.api.configuration.*;
            import dev.openfga.sdk.api.client.model.*;
            import dev.openfga.sdk.api.model.*;
            import java.util.List;
            import java.util.Map;
            import java.util.ArrayList;
            import dev.openfga.sdk.api.configuration.ClientReadOptions;

            public class Example {
                public static void main(String[] args) throws Exception {
                    var config = new ClientConfiguration()
                        .apiUrl(System.getenv("FGA_API_URL"))
                        .storeId(System.getenv("FGA_STORE_ID"));
                    var fgaClient = new OpenFgaClient(config);
                    
                    var body = new ClientReadRequest()
                        .user("user:anne")
                        .relation("reader")
                        ._object("document:budget");
                    var options = new ClientReadOptions()
                        .pageSize(20);
                    var response = fgaClient.read(body, options).get();
                }
            }
        - lang: bash
          label: curl
          source: >-
            # Set FGA_API_URL to the URL of your OpenFGA server.

            # Set FGA_STORE_ID to your store ID.

            # These examples use a server with authentication disabled.

            # For authenticated servers, see
            /docs/getting-started/setup-sdk-client.


            curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
              -H "content-type: application/json" \
              -d '{
              "tuple_key": {
                "user": "user:anne",
                "relation": "reader",
                "object": "document:budget"
              },
              "page_size": 20
            }'
components:
  schemas:
    ReadBody:
      properties:
        consistency:
          allOf:
            - $ref: '#/components/schemas/ConsistencyPreference'
            - description: >-
                Controls the consistency preference for this request. Default
                value is `UNSPECIFIED`, which has the same behavior as
                `MINIMIZE_LATENCY`.
        continuation_token:
          example: >-
            eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==
          type: string
        page_size:
          example: 50
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        tuple_key:
          $ref: '#/components/schemas/ReadRequestTupleKey'
      type: object
    ReadResponse:
      properties:
        continuation_token:
          description: The continuation token is empty if there are no more tuples.
          example: >-
            eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==
          type: string
        tuples:
          items:
            allOf:
              - $ref: '#/components/schemas/Tuple'
              - type: object
          type: array
      required:
        - tuples
        - continuation_token
      type: object
    ValidationErrorMessageResponse:
      example:
        code: validation_error
        message: Generic validation error
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
      type: object
    UnauthenticatedResponse:
      example:
        code: unauthenticated
        message: unauthenticated
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
      type: object
    ForbiddenResponse:
      example:
        code: forbidden
        message: the principal is not authorized to perform the action
      properties:
        code:
          $ref: '#/components/schemas/AuthErrorCode'
        message:
          type: string
      type: object
    PathUnknownErrorMessageResponse:
      example:
        code: undefined_endpoint
        message: Endpoint not enabled
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorCode'
        message:
          type: string
      type: object
    AbortedMessageResponse:
      example:
        code: '10'
        message: transaction conflict
      properties:
        code:
          type: string
        message:
          type: string
      type: object
    UnprocessableContentMessageResponse:
      example:
        code: throttled_timeout_error
        message: timeout due to throttling on complex request
      properties:
        code:
          $ref: '#/components/schemas/UnprocessableContentErrorCode'
        message:
          type: string
      type: object
    InternalErrorMessageResponse:
      example:
        code: internal_error
        message: Internal Server Error
      properties:
        code:
          $ref: '#/components/schemas/InternalErrorCode'
        message:
          type: string
      type: object
    ConsistencyPreference:
      default: UNSPECIFIED
      description: |-
        Controls the consistency preferences when calling the query APIs.

         - UNSPECIFIED: Default if not set. Behavior will be the same as MINIMIZE_LATENCY.
         - MINIMIZE_LATENCY: Minimize latency at the potential expense of lower consistency.
         - HIGHER_CONSISTENCY: Prefer higher consistency, at the potential expense of increased latency.
      enum:
        - UNSPECIFIED
        - MINIMIZE_LATENCY
        - HIGHER_CONSISTENCY
      example: MINIMIZE_LATENCY
      type: string
    ReadRequestTupleKey:
      properties:
        object:
          example: document:2021-budget
          maxLength: 256
          type: string
        relation:
          example: reader
          maxLength: 50
          type: string
        user:
          example: user:anne
          maxLength: 512
          type: string
      type: object
    Tuple:
      properties:
        key:
          $ref: '#/components/schemas/TupleKey'
        timestamp:
          format: date-time
          type: string
      required:
        - key
        - timestamp
      type: object
    ErrorCode:
      default: no_error
      enum:
        - no_error
        - validation_error
        - authorization_model_not_found
        - authorization_model_resolution_too_complex
        - invalid_write_input
        - cannot_allow_duplicate_tuples_in_one_request
        - cannot_allow_duplicate_types_in_one_request
        - cannot_allow_multiple_references_to_one_relation
        - invalid_continuation_token
        - invalid_tuple_set
        - invalid_check_input
        - invalid_expand_input
        - unsupported_user_set
        - invalid_object_format
        - write_failed_due_to_invalid_input
        - authorization_model_assertions_not_found
        - latest_authorization_model_not_found
        - type_not_found
        - relation_not_found
        - empty_relation_definition
        - invalid_user
        - invalid_tuple
        - unknown_relation
        - store_id_invalid_length
        - assertions_too_many_items
        - id_too_long
        - authorization_model_id_too_long
        - tuple_key_value_not_specified
        - tuple_keys_too_many_or_too_few_items
        - page_size_invalid
        - param_missing_value
        - difference_base_missing_value
        - subtract_base_missing_value
        - object_too_long
        - relation_too_long
        - type_definitions_too_few_items
        - type_invalid_length
        - type_invalid_pattern
        - relations_too_few_items
        - relations_too_long
        - relations_invalid_pattern
        - object_invalid_pattern
        - query_string_type_continuation_token_mismatch
        - exceeded_entity_limit
        - invalid_contextual_tuple
        - duplicate_contextual_tuple
        - invalid_authorization_model
        - unsupported_schema_version
        - cancelled
        - invalid_start_time
      type: string
    AuthErrorCode:
      default: no_auth_error
      enum:
        - no_auth_error
        - auth_failed_invalid_subject
        - auth_failed_invalid_audience
        - auth_failed_invalid_issuer
        - invalid_claims
        - auth_failed_invalid_bearer_token
        - bearer_token_missing
        - unauthenticated
        - forbidden
      type: string
    NotFoundErrorCode:
      default: no_not_found_error
      enum:
        - no_not_found_error
        - undefined_endpoint
        - store_id_not_found
        - unimplemented
      type: string
    UnprocessableContentErrorCode:
      default: no_throttled_error_code
      enum:
        - no_throttled_error_code
        - throttled_timeout_error
      type: string
    InternalErrorCode:
      default: no_internal_error
      enum:
        - no_internal_error
        - internal_error
        - deadline_exceeded
        - already_exists
        - resource_exhausted
        - failed_precondition
        - aborted
        - out_of_range
        - unavailable
        - data_loss
      type: string
    TupleKey:
      properties:
        condition:
          $ref: '#/components/schemas/RelationshipCondition'
        object:
          example: document:2021-budget
          maxLength: 256
          type: string
        relation:
          example: reader
          maxLength: 50
          type: string
        user:
          example: user:anne
          maxLength: 512
          type: string
      required:
        - user
        - relation
        - object
      type: object
    RelationshipCondition:
      properties:
        context:
          description: >-
            Additional context/data to persist along with the condition.

            The keys must match the parameters defined by the condition, and the
            value types must

            match the parameter type definitions.
          type: object
        name:
          description: >-
            A reference (by name) of the relationship condition defined in the
            authorization model.
          example: condition1
          maxLength: 256
          type: string
      required:
        - name
      type: object

````