# General Translation Platform: 查询文件元数据
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/query-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 获取源文件及翻译后的文件的元数据（包括审批、完成和发布日期），单次最多支持 100 个选择器。需要 project:files:read 权限。

{/* 此文件由 Fumadocs 生成。请勿直接编辑此文件。如需修改，请重新运行生成命令。 */}

## Endpoint

`POST https://api.gtx.dev/v2/projects/{projectId}/files/query`

**Operation ID:** `queryFiles`

**Tags:** `Files`

**Summary:** Query file metadata

Get source and translated file metadata, including approval, completion, and publication dates, for up to 100 selectors. Requires `project:files:read`.

Authentication: required. Send an API key in the `Authorization: Bearer <key>` header when authenticating.

### Parameters

- `projectId` (path, string, required)
- `gt-api-version` (header, "2026-10-08.v1", required): API contract version. Must be `2026-10-08.v1` or later; requests without it or with an older version return 400.

### Request body (required)

Body (`application/json`, object):
- `files` (object[], required): Files to describe, at most 100. Each selector is a source file, or with `locale` one translation; a selector repeated field for field is rejected.
  - `fileId` (string, required)
  - `branchId` (string): Branch ID. Defaults to the project default branch.
  - `versionId` (string): Source version ID. Defaults to the branch head.
  - `locale` (string): Translation locale. Omit to read the source file.

### Responses

**200**: One result per selector, in selector order. The request is a read: it creates and changes nothing and is safe to retry, and uses POST only to carry the selectors in the body.
Response body (`application/json`, object):
- `results` (object[], required): One result per selector, in selector order.
  - `status` ("found" | "pending" | "not_found", required): `found` with the metadata; `pending` when the translation is stored but not completed yet, for example during a layout pass; `not_found` when there is neither, including while its translation job has not stored the translation yet. Only completed translations are `found`.
  - `branchId` (string): Branch ID. Absent only when `status` is `not_found` and no branch resolves: the selector names no branch and the project has no default branch.
  - `fileId` (string, required)
  - `versionId` (string): Present when `status` is `found` or `pending`.
  - `fileName` (string): Present when `status` is `found` for a source file.
  - `fileFormat` ("GTJSON" | "MDX" | "JSON" | "YAML" | "MD" | "TS" | "JS" | "HTML" | "TXT" | "PO" | "POT" | "TWILIO_CONTENT_JSON" | "LOTTIE" | "SVG" | "XCSTRINGS" | "DOT_STRINGS" | "DOT_STRINGSDICT" | "ANDROID_STRINGS" | "SRT" | "RESX" & object)
  - `dataFormat` (string | null): Present when `status` is `found`.
  - `createdAt` (string (date-time)): Present when `status` is `found`.
  - `updatedAt` (string (date-time)): Present when `status` is `found`.
  - `approvedAt` (string | null (date-time)): Present when `status` is `found` for a translation.
  - `publishedAt` (string | null (date-time)): Present when `status` is `found`.
  - `completedAt` (string | null (date-time)): Present when `status` is `found` for a translation.
  - `locales` (string[]): Present when `status` is `found` for a source file.
  - `sourceLocale` (string): Present when `status` is `found` for a source file.
  - `locale` (string): The selector's locale, as requested; present only for translations.

**400**: The request is malformed or failed validation, including a selector repeated field for field or more than 100 selectors. No file is read.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**401**: Authentication is missing or invalid.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**403**: The caller is authenticated but not allowed to perform this operation or access the requested resource.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**413**: The request, or the data it would return, exceeds a size or item limit.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**415**: The request body's Content-Type is missing or not supported. Send the body as application/json.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**429**: Too many requests. The rate limit was exceeded.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

**500**: An unexpected server error occurred.
Response body (`application/json`, object):
- `error` (string, required)

Response body (`text/html`, string):

Complete OpenAPI 3.1 specification: https://generaltranslation.com/openapi.yaml

OpenAPI schema: [openapi.json](https://generaltranslation.com/openapi.json)

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.