---
title: "File Metadata"
description: "Extract and write file metadata"
canonical_url: "https://cloudconvert.com/docs/operations/file-metadata"
---
# File Metadata

> Extract and write file metadata

## Extract Metadata

Create a task to extract metadata from files. Under the hood, this is using exiftool. You can use this operation to get the number of pages of PDFs or to get the resolution of images/videos.

For audio and video files you can alternatively set `"engine": "ffmpeg"` to get the output of `ffprobe` instead: the container `format`, all `streams` with their codec details, and the `chapters` of the file.

The metadata operation does not consume any conversion credits.

#### Task Parameters

### metadata task parameters

- `operation` _string_ required: Value is `metadata`.
- `input` _string or array of task names_: The input task name(s) for this task.
- `input_format` _string_: The current format of the file, e.g. pdf. If not set, the extension of the input file is used as input format.
- `engine` _string_: Use a specific engine for the conversion.
- `engine_version` _string_: Use a specific engine version for the conversion.
- `timeout` _integer_: Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Additional operation-specific parameters can be available depending on the input format and output format. Use the [operations API](https://cloudconvert.com/docs/raw/api-reference/operations.md#list-operations) to identify these dynamic parameters, for example by filtering for `metadata` and including `options`: `GET https://api.cloudconvert.com/v2/operations?filter[operation]=metadata&include=options`.

### Example job

Raw request:

```json
{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}
```

CLI:

```bash
# Install the CloudConvert CLI: npm install -g cloudconvert-cli
# The CloudConvert CLI does not support these task types: metadata.
```

cURL:

```bash
$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
    -H "Authorization: Bearer API_KEY" \
    -H "Content-type: application/json" \
    -d '{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}' 
```

PHP:

```php
use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

$cloudconvert = new CloudConvert(['api_key' => 'API_KEY']);

$job = (new Job())
   ->addTask(
       (new Task('import/url', 'import-my-file'))
         ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
     )
   ->addTask(
       (new Task('metadata', 'convert-my-file'))
         ->set('input', 'import-my-file')
     )
   ->addTask(
       (new Task('export/url', 'export-my-file'))
         ->set('input', 'convert-my-file')
     ); 

$cloudconvert->jobs()->create($job);
```

Node.js:

```js
import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});
```

Python:

```python
import cloudconvert

cloudconvert.configure(api_key='API_KEY')

cloudconvert.Job.create(payload={
    'tasks': {
        'import-my-file': {
            'operation': 'import/url',
            'url': 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf'
        },
        'convert-my-file': {
            'operation': 'metadata',
            'input': 'import-my-file'
        },
        'export-my-file': {
            'operation': 'export/url',
            'input': 'convert-my-file'
        }
    }
})
```

#### Example Response

You can find an example result of of the metadata extraction of a PDF below:

<code-collapse name="Example Response">

```json
{
  "data": {
    "id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
    "tag": "myjob-123",
    "status": "finished",
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "tasks": [
        {
    "id": "c85f3ca9-164c-4e89-8ae2-c08192a7cb08",
    "operation": "metadata",
    "status": "finished",
    "message": null,
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "ended_at": "2018-09-19T14:42:58+00:00",
    "depends_on_tasks": {},
    "engine": "exiftool",
    "engine_version": "12.07",
    "payload": {
      "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
      "input_format": "pdf"
    },
    "result": {
      "metadata": {
        "SourceFile": "zombies.pdf",
        "ExifToolVersion": 12.07,
        "FileName": "zombies.pdf",
        "Directory": ".",
        "FileSize": "169 kB",
        "FileModifyDate": "2020:08:18 14:04:31+00:00",
        "FileAccessDate": "2020:10:07 14:15:45+00:00",
        "FileInodeChangeDate": "2020:08:18 14:04:31+00:00",
        "FilePermissions": "rw-r--r--",
        "FileType": "PDF",
        "FileTypeExtension": "pdf",
        "MIMEType": "application/pdf",
        "PDFVersion": 1.4,
        "Linearized": "Yes",
        "Author": "Doug",
        "CreateDate": "2014:05:14 13:14:52-05:00",
        "ModifyDate": "2014:05:14 13:36:57-05:00",
        "XMPToolkit": "Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26        ",
        "Producer": "ScanSoft PDF Create! 7",
        "CreatorTool": "Microsoft Word - CONPLAN 8888-11 ... Pentagon Zombie Plan ... Counter Zombie Dominance 2011",
        "MetadataDate": "2014:05:14 13:36:57-05:00",
        "Format": "application/pdf",
        "Title": "Microsoft Word - CONPLAN 8888-11 ... Pentagon Zombie Plan ... Counter Zombie Dominance 2011",
        "Creator": "Doug",
        "DocumentID": "uuid:406c2972-c2bd-4470-95ad-1bfb6efb5258",
        "InstanceID": "uuid:c4d76637-aaa4-4e08-8a28-149644c2400c",
        "PageMode": "UseNone",
        "PageCount": 31
      }
    }
  }
    ]
  }
}
```

</code-collapse>

<tip to="https://cloudconvert.com/job-builder?operation=metadata">

Use the **Job Builder** to generate and try out metadata jobs.

</tip>

## Write Metadata

Create a task to write file metadata. Under the hood, this is using exiftool. You can use this operation to write any XMP or IPTC metadata, such as Author, Title, Copyright etc. You can find an example request to set PDF metadata below.

Possible metadata keys include `Title`, `Author`, `Creator`, `Producer`. You can find all possible properties in the [exiftool documentation](https://exiftool.org/TagNames/).

#### Task Parameters

### metadata/write task parameters

- `operation` _string_ required: Value is `metadata/write`.
- `input` _string or array of task names_: The input task name(s) for this task.
- `input_format` _string_: The current format of the file, e.g. pdf. If not set, the extension of the input file is used as input format.
- `engine` _string_: Use a specific engine for the conversion.
- `engine_version` _string_: Use a specific engine version for the conversion.
- `metadata` _dictionary_ required: Object of metadata to write.
- `filename` _string_: Choose a filename (including extension) for the output file.
- `timeout` _integer_: Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Additional operation-specific parameters can be available depending on the input format and output format. Use the [operations API](https://cloudconvert.com/docs/raw/api-reference/operations.md#list-operations) to identify these dynamic parameters, for example by filtering for `metadata/write` and including `options`: `GET https://api.cloudconvert.com/v2/operations?filter[operation]=metadata/write&include=options`.

### Example job

Raw request:

```json
{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}
```

CLI:

```bash
# Install the CloudConvert CLI: npm install -g cloudconvert-cli
# The CloudConvert CLI does not support these task types: metadata/write.
```

cURL:

```bash
$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
    -H "Authorization: Bearer API_KEY" \
    -H "Content-type: application/json" \
    -d '{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}' 
```

PHP:

```php
use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

$cloudconvert = new CloudConvert(['api_key' => 'API_KEY']);

$job = (new Job())
   ->addTask(
       (new Task('import/url', 'import-my-file'))
         ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
     )
   ->addTask(
       (new Task('metadata/write', 'convert-my-file'))
         ->set('input', 'import-my-file')
         ->set('metadata', '[object Object]')
     )
   ->addTask(
       (new Task('export/url', 'export-my-file'))
         ->set('input', 'convert-my-file')
     ); 

$cloudconvert->jobs()->create($job);
```

Node.js:

```js
import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});
```

Python:

```python
import cloudconvert

cloudconvert.configure(api_key='API_KEY')

cloudconvert.Job.create(payload={
    'tasks': {
        'import-my-file': {
            'operation': 'import/url',
            'url': 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf'
        },
        'convert-my-file': {
            'operation': 'metadata/write',
            'input': 'import-my-file',
            'metadata': {
                'Author': 'Richard Hendricks',
                'Title': 'The Pied Piper algorithm.',
                'Producer': 'CloudConvert',
                'Creator': 'CloudConvert'
            }
        },
        'export-my-file': {
            'operation': 'export/url',
            'input': 'convert-my-file'
        }
    }
})
```

<tip to="https://cloudconvert.com/job-builder?operation=metadata/write">

Use the **Job Builder** to generate and try out metadata/write jobs.

</tip>


## Sitemap

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