# General Translation Platform: queryFileData
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/translation/query-file-data.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Check translation status and metadata for uploaded or translated files. API reference for queryFileData.

Queries data about one or more source or translation files with General Translation. Use it to monitor translation progress, check completion status, and see which translations are available.

## Overview [#overview]

Call `queryFileData` with an object listing the source and/or translated files to query. It returns metadata for each requested file.

```typescript
const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });

const result = await gt.queryFileData({
  sourceFiles: [{ fileId: 'file-123', versionId: 'version-456', branchId: 'branch-789' }],
  translatedFiles: [
    { fileId: 'file-123', versionId: 'version-456', branchId: 'branch-789', locale: 'es' },
  ],
});
```

Signature:

```typescript
queryFileData(
  data: FileDataQuery,
  options?: CheckFileTranslationsOptions
): Promise<FileDataResult>
```

*Note: `queryFileData` requires an API key (including the deprecated `devApiKey` alias), plus `projectId` on the GT instance.*

## How it works [#how-it-works]

- **Completion.** A translation is complete when its `completedAt` is not `null`.
- **Lifecycle.** A completed translation may still require approval (`approvedAt`) before it is published (`publishedAt`).
- **Batch monitoring.** Query many files at once for efficient status checking across multiple translation jobs.
- **Locale codes.** Returned locales use your [configured spellings and aliases](/docs/platform/core/reference/gt-class/constructor#how-it-works) where possible. If multiple aliases identify the same locale, the first configured match is used. Equivalent requested spellings may share a response label.
- **Versioning.** All file queries require `branchId` for versioning with branch support.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`data`](#data) | Object containing source and translation file queries. | `FileDataQuery` | No | — |
| [`options`](#options) | Configuration for the request. | `CheckFileTranslationsOptions` | Yes | — |

### `data` [#data]

**Type** `FileDataQuery` · **Required**

The files to query, split into source and translated files:

```typescript
type FileDataQuery = {
  sourceFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
  }[];
  translatedFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
    locale: string;
  }[];
};
```

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `sourceFiles` | Array of source file queries. | `object[]` | Yes |
| `translatedFiles` | Array of translated file queries. | `object[]` | Yes |

### `options` [#options]

**Type** `CheckFileTranslationsOptions` · **Optional**

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `timeout` | Request timeout in milliseconds. | `number` | Yes |

## Returns [#returns]

**Type** `Promise<FileDataResult>`

Resolves to a `FileDataResult` containing metadata for the requested source and translated files:

```typescript
type FileDataResult = {
  sourceFiles?: {
    branchId: string;
    fileId: string;
    versionId: string;
    fileName: string;
    fileFormat: string;
    dataFormat: string | null;
    createdAt: string;
    updatedAt: string;
    publishedAt: string | null;
    locales: string[];
    sourceLocale: string;
  }[];
  translatedFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
    locale: string;
    fileFormat: string;
    dataFormat: string | null;
    completedAt: string | null;
    approvedAt: string | null;
    publishedAt: string | null;
    createdAt: string;
    updatedAt: string;
  }[];
};
```

| Property | Description | Type |
| --- | --- | --- |
| `sourceFiles` | Array of source file data. | `object[]` |
| `translatedFiles` | Array of translation status data. | `object[]` |

## Examples [#examples]

```typescript title="index.ts"
import { GT } from 'generaltranslation';
import type { FileUpload } from 'generaltranslation/types';

const fileContents = '{"greeting":"Hello"}';
const filePath = 'en.json';

// (1) Create a GT instance
const targetLocales = ['es', 'fr', 'de'];
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// (2) Upload the file
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [{ source: fileUpload }];
const { uploadedFiles } = await gt.uploadSourceFiles(files, { sourceLocale: 'en' });

// (3) Enqueue the file translation job
const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: targetLocales,
});

// (4) Wait for all translations to be completed
const { fileId, versionId, branchId } = uploadedFiles[0];
const translatedFileQueries = targetLocales.map((locale) => ({
  fileId,
  versionId,
  branchId,
  locale,
}));

const jobs = await gt.awaitJobs(enqueueResult, { timeoutSeconds: 300 });
if (!jobs.complete || jobs.jobs.some((job) => job.status !== 'completed')) {
  throw new Error('Translation jobs did not complete successfully');
}
const status = await gt.queryFileData({ translatedFiles: translatedFileQueries });
if (status.translatedFiles?.length !== translatedFileQueries.length ||
    status.translatedFiles.some((file) => file.completedAt === null)) {
  throw new Error('Translations are not ready to download');
}

// (5) Download the files
const downloadResult = await gt.downloadFileBatch(
  translatedFileQueries
);
```

## Notes [#notes]

- A translation is complete when `completedAt` is not `null`.
- Completed translations may still require approval (`approvedAt`) before being published (`publishedAt`).
- Use this method for efficient status checking when monitoring multiple translation jobs.
- All file queries require `branchId` for versioning with branch support.

## Sitemap

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