> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # List an agent’s files > The files in the agent’s own file system, by path, and how much of its limits they all use. Anyone in the org can read them. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agent_id}/files openapi: 3.1.0 info: title: GuidingHand API version: 1.0.0 description: >- Create sessions (an invite link with a code for the person at the computer), run tasks on their computer with one of your agents, follow them, answer their questions and approvals, and fetch history and recordings. Test your agents with evals: test cases on fresh machines, run in test sets, scored by a check script or a rubric. Agents are versioned (save a draft, publish it), have tools (their own file system, and your HTTP endpoints), and every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners paths: /v1/agents/{agent_id}/files: parameters: - name: agent_id in: path required: true description: The agent’s id, e.g. `billing` or `default`. schema: type: string get: tags: - Agent files summary: List an agent’s files description: >- The files in the agent’s own file system, by path, and how much of its limits they all use. Anyone in the org can read them. operationId: listAgentFiles parameters: - name: folder in: query required: false description: Only the files in this folder, like `/notes`. schema: type: string - name: q in: query required: false description: >- Search: only files whose path has the text containing this text (case-insensitive, up to 100 characters). schema: type: string maxLength: 100 - name: limit in: query required: false description: >- How many to return, 1 to 100. Without `limit` or `cursor`, the whole list in one page. schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false description: '`next_cursor` from the previous page.' schema: type: string - name: include in: query required: false description: '`total_count` adds how many match across every page.' schema: type: string example: total_count responses: '200': description: OK content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/AgentFile' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page. usage: $ref: '#/components/schemas/FileUsage' total_count: type: integer description: >- How many match the filters across every page. Only with `include=total_count`. '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '404': $ref: '#/components/responses/E404' components: schemas: AgentFile: type: object properties: object: const: agent_file agent_id: type: string example: billing path: type: string example: /notes/customers.md description: Always starts with `/`. bytes: type: integer description: Its size in UTF-8. created_at: type: string format: date-time updated_at: type: string format: date-time updated_by: $ref: '#/components/schemas/FileEditor' content: type: string description: The file’s text. Only when you get or write one file. FileUsage: type: object description: How much of its limits the agent’s files use. properties: files: type: integer bytes: type: integer limits: type: object properties: file_bytes: type: integer example: 1000000 agent_bytes: type: integer example: 25000000 files: type: integer example: 1000 FileEditor: oneOf: - title: Person type: object description: A person in the org (in the console). properties: type: const: user email: type: - string - 'null' example: jane@acme.com - title: API key type: object description: One of the org’s API keys. properties: type: const: api_key key_id: type: string name: type: - string - 'null' example: Zendesk prefix: type: - string - 'null' description: The key’s first characters. example: gh_live_AbC1 - title: Agent type: object description: 'An agent during a task: its own file writes.' properties: type: const: agent task_id: type: string - type: 'null' description: >- Who last wrote the file: a person, an API key, or the agent itself during a task (`task_id`). Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance can’t cover a minute; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). On `/respond`: `already_answered` (someone answered or decided first: see `answered_by`) or `not_pending` (that question or approval isn’t open any more). The GuidingHand app hears two more, which the API never returns: `customer_answers_off` and `customer_approvals_off` (the agent keeps its questions or approvals for your team). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). answered_by: type: string enum: - customer - operator - timeout description: >- With `already_answered`: who answered or decided first (`customer`: the person at the computer; `timeout`: nobody decided an approval within the agent’s `approval_timeout_minutes`, so it was denied). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' responses: E400: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' E401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' E404: description: Not found in this org. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ````