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

# Get files

> List files.

<Info>
  **Tool** `get_files` · **Behavior** Read-only
</Info>

List files. Pass `id` to fetch one file (and poll its upload `status`), `q` to search files you can access (optionally narrowed by `scope`), or `project_id` to list a project's files (add `q` to search within them). Always returns a `files` array — empty when nothing matches. Calling with none of `id`, `q`, or `project_id` is an error: there is no full file listing, only lookup, search, and per-project listing.

## Input parameters

<ParamField body="id" type="string (uuid)">
  Fetch one file by id. This is also the upload-readiness poll: the returned file carries `status` (`ready` once processing finishes). Cannot be combined with `q` or `project_id`.
</ParamField>

<ParamField body="q" type="string">
  Search across files you can access, ranked by relevance (max 100 results). Combine with `project_id` to search within one project.
</ParamField>

<ParamField body="scope" type="'my-files' | 'shared-with-me' | 'organization'">
  Optional search scope filter: "my-files", "shared-with-me", or "organization". Applies to `q` searches only.
</ParamField>

<ParamField body="project_id" type="string (uuid)">
  Restrict to files in this project (e.g. a project holding a set of contracts). Alone, lists the project's files; with `q`, searches within them. Cannot be combined with `id` or `scope`.
</ParamField>

## Response

<ResponseField name="files" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="string (uuid)" />

    <ResponseField name="name" type="string" />

    <ResponseField name="size" type="number" />

    <ResponseField name="content_type" type="string" />

    <ResponseField name="status" type="'ready' | 'extracting' | 'embedding' | 'failed'" />

    <ResponseField name="created_at" type="string" />

    <ResponseField name="extraction_error" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="hint" type="string">
  Plain-language next step for a single-file lookup (ready to use, still processing so poll again, or failed). Absent for searches and multi-file results.
</ResponseField>