---
title: "Query file metadata"
method: POST
path: "/v2/projects/{projectId}/files/query"
tags: ["Files"]
---

# Query file metadata

`POST /v2/projects/{projectId}/files/query`

## Request

- Base URL: `https://api.gtx.dev`
- URL: `https://api.gtx.dev/v2/projects/{projectId}/files/query`
- Auth: HTTP bearer

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

## Path parameters

- `projectId` string, required

## Headers

- `gt-api-version` '2025-01-01.v0' | '2025-11-03.v1' | '2026-02-18.v1' | '2026-03-06.v1' | '2026-10-08.v1', required

## Request body

- 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.

## Response `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.

- 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' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4': Present when `status` is `found`.
    - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING' | 'MESSAGE_TREE'
    - `createdAt` string, date-time: Present when `status` is `found`.
    - `updatedAt` string, date-time: Present when `status` is `found`.
    - `approvedAt` string, date-time, nullable: Present when `status` is `found` for a translation.
    - `publishedAt` string, date-time, nullable: Present when `status` is `found`.
    - `completedAt` string, date-time, nullable: 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.

## Other responses

- `400`: The request is malformed or failed validation, including a selector repeated field for field or more than 100 selectors. No file is read.
- `401`: Authentication is missing or invalid.
- `403`: The caller is authenticated but not allowed to perform this operation or access the requested resource.
- `413`: The request, or the data it would return, exceeds a size or item limit.
- `415`: The request body's Content-Type is missing or not supported, or its Content-Encoding is not supported. Send the body as application/json, uncompressed or gzip-encoded.
- `429`: Too many requests. The rate limit was exceeded.
- `500`: An unexpected server error occurred.

## Changes

- **2026-11-14** `1ebafb7f823e`: 1 warning
  - added the new `MESSAGE_TREE` enum value to the `results/items/dataFormat/anyOf[#/components/schemas/DataFormat]/` response property for the response status `200`
- **2026-11-06** `39f0059275f1`: 16 warning
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `400`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `401`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `403`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `413`
  - …12 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/generaltranslation/apis/general-translation-api/changes/v2/projects/:projectId/files/query/post.md)

---

[API](https://skmtc.dev/generaltranslation/apis/general-translation-api.md) - [All operations](https://skmtc.dev/generaltranslation/apis/general-translation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/generaltranslation/apis/general-translation-api/revisions/1ebafb7f823e?raw)
