> ## 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. # List objects a user is related to > The ListObjects API returns a list of all the objects of the given type that the user has a relation with. To arrive at a result, the API uses: - An [authorization model](/docs/getting-started/configure-model) - Explicit tuples written through the Write API - Contextual tuples present in the request - Implicit tuples that exist by virtue of applying set theory. For example: `document:2021-budget#viewer@document:2021-budget#viewer` In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`. An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used. > **Note:** We recommend you specify authorization model ID for better performance. You may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`. You may also provide a `context` object that is used to evaluate the conditioned tuples in the system. > **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response contains the related objects in an array in the "objects" field of the response and are strings in the object format `:` (e.g. "document:roadmap"). The number of objects in the response array are limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE` and by the upper bound specified in the flag `OPENFGA_LIST_OBJECTS_MAX_RESULTS`, whichever is hit first. The objects given are not sorted, and therefore two identical calls can give a given different set of objects. ## OpenAPI ````yaml https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json post /stores/{store_id}/list-objects 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}/list-objects: post: tags: - Relationship Queries summary: List objects a user is related to description: >- The ListObjects API returns a list of all the objects of the given type that the user has a relation with. To arrive at a result, the API uses: - An [authorization model](/docs/getting-started/configure-model) - Explicit tuples written through the Write API - Contextual tuples present in the request - Implicit tuples that exist by virtue of applying set theory. For example: `document:2021-budget#viewer@document:2021-budget#viewer` In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`. An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used. > **Note:** We recommend you specify authorization model ID for better performance. You may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`. You may also provide a `context` object that is used to evaluate the conditioned tuples in the system. > **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response contains the related objects in an array in the "objects" field of the response and are strings in the object format `:` (e.g. "document:roadmap"). The number of objects in the response array are limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE` and by the upper bound specified in the flag `OPENFGA_LIST_OBJECTS_MAX_RESULTS`, whichever is hit first. The objects given are not sorted, and therefore two identical calls can give a given different set of objects. operationId: ListObjects parameters: - in: path name: store_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ListObjectsBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListObjectsResponse' 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, authorizationModelId: process.env.FGA_MODEL_ID, // Optional; requests can override this. }); async function main() { const body = { "user": "user:anne", "relation": "reader", "type": "document" }; const options = { }; const response = await fgaClient.listObjects(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"), AuthorizationModelId: os.Getenv("FGA_MODEL_ID"), // Optional; requests can override this. }) if err != nil { panic(err) } body := ClientListObjectsRequest{ User: "user:anne", Relation: "reader", Type: "document", } options := ClientListObjectsOptions{ } data, err := fgaClient.ListObjects(context.Background()).Body(body).Options(options).Execute() if err != nil { panic(err) } _ = data } - 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"), AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional; requests can override this. }); var body = new ClientListObjectsRequest { User = "user:anne", Relation = "reader", Type = "document", }; var options = new ClientListObjectsOptions { }; var response = await fgaClient.ListObjects(body, options); - lang: python label: Python source: >- import asyncio import os from openfga_sdk.client import OpenFgaClient, ClientConfiguration from openfga_sdk.client.models import ClientListObjectsRequest, ClientTuple from openfga_sdk.models import RelationshipCondition async def main(): configuration = ClientConfiguration( api_url=os.environ.get("FGA_API_URL"), store_id=os.environ.get("FGA_STORE_ID"), authorization_model_id=os.environ.get("FGA_MODEL_ID"), # Optional; requests can override this. ) async with OpenFgaClient(configuration) as fga_client: body = ClientListObjectsRequest( user="user:anne", relation="reader", type="document", ) options = { } response = await fga_client.list_objects(body, 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; 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")) .authorizationModelId(System.getenv("FGA_MODEL_ID")); // Optional; requests can override this. var fgaClient = new OpenFgaClient(config); var body = new ClientListObjectsRequest() .user("user:anne") .relation("reader") .type("document"); var options = new ClientListObjectsOptions(); var response = fgaClient.listObjects(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/list-objects" \ -H "content-type: application/json" \ -d '{ "authorization_model_id": "'"$FGA_MODEL_ID"'", "user": "user:anne", "relation": "reader", "type": "document" }' components: schemas: ListObjectsBody: properties: authorization_model_id: example: 01G5JAVJ41T49E9TT3SKVS7X1J type: string 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`. context: description: >- Additional request context that are used to evaluate any ABAC conditions encountered in the query evaluation. type: object contextual_tuples: $ref: '#/components/schemas/ContextualTupleKeys' relation: example: reader type: string type: example: document type: string user: example: user:anne maxLength: 512 minLength: 1 type: string required: - type - relation - user type: object ListObjectsResponse: properties: objects: example: - document:roadmap - document:planning items: type: string type: array required: - objects 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 ContextualTupleKeys: properties: tuple_keys: items: allOf: - $ref: '#/components/schemas/TupleKey' - type: object maxItems: 100 type: array required: - tuple_keys 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 ````