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

# Get a file download link

> Returns a short-lived link to the original file that was uploaded to Metal, such as the PDF or spreadsheet that a document's text came from.

Pass the file ID, which is the `dataEntity` value on a document from [Search documents](/api-reference/documents/search-documents) or [Get documents by ids](/api-reference/documents/get-documents-by-ids).

An API key acts as the user who created it. The key can get links only for files in its own organization that this user can read.

The link expires one hour after Metal issues it. Anyone who has the link can download the file until it expires, so do not log or share it. To download the file again after the link expires, call this endpoint again.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/data-entities/{id}/download-url
openapi: 3.1.0
info:
  title: Metal API
  version: 1.0.0
  description: >-
    REST API for Metal, the AI context layer for financial firms. Manage
    companies, deals, people, documents, activities, enrichments, scores,
    screenings, lists, workflows, and more. All endpoints are versioned under
    /v1, return JSON, and are scoped to the organization that owns your API key.
  contact:
    name: Metal Support
    email: support@metal.ai
    url: https://www.metal.ai
servers:
  - url: https://api.metal.ai
    description: Production
security:
  - MetalClientId: []
    MetalApiKey: []
tags:
  - name: API keys
    description: Check which API key a request is using.
  - name: Companies
    description: Manage and enrich companies.
  - name: Deals
    description: Track opportunities through your pipeline.
  - name: People
    description: Manage contacts and relationships.
  - name: Documents
    description: Search and retrieve ingested documents.
  - name: Activities
    description: Log and search meetings, calls, and other interactions.
  - name: Enrichments
    description: Read and write enriched property values on resources.
  - name: Scores
    description: Score companies and deals against scoring frameworks.
  - name: Screenings
    description: Run and manage AI-powered company screenings.
  - name: Lists
    description: Organize and enrich resources in bulk.
  - name: Tags
    description: Label companies, deals, and lists.
  - name: Industries
    description: Manage your organization's industry taxonomy.
  - name: Sectors
    description: Manage sectors within an industry.
  - name: Subsectors
    description: Manage subsectors within a sector.
  - name: Workflows
    description: Run and monitor AI workflows.
  - name: Data
    description: Query time-series metrics and observations.
  - name: Teams
    description: Manage deal teams and their members.
  - name: Workspaces
    description: Organize documents and data by workspace.
  - name: Inference
    description: Run single LLM completions scoped to your organization.
paths:
  /v1/data-entities/{id}/download-url:
    get:
      tags:
        - Documents
      summary: Get a file download link
      description: >-
        Returns a short-lived link to the original file that was uploaded to
        Metal, such as the PDF or spreadsheet that a document's text came from.


        Pass the file ID, which is the `dataEntity` value on a document from
        [Search documents](/api-reference/documents/search-documents) or [Get
        documents by ids](/api-reference/documents/get-documents-by-ids).


        An API key acts as the user who created it. The key can get links only
        for files in its own organization that this user can read.


        The link expires one hour after Metal issues it. Anyone who has the link
        can download the file until it expires, so do not log or share it. To
        download the file again after the link expires, call this endpoint
        again.
      operationId: getDocumentDownloadUrl
      parameters:
        - name: id
          in: path
          required: true
          description: The file ID. Use the `dataEntity` value from a document.
          schema:
            type: string
            example: 665f1c2a9b1e4a0012a3b4c5
      responses:
        '200':
          description: A download link for the original file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DocumentDownloadUrl'
        '400':
          description: >-
            The file ID is not valid, or the file cannot be downloaded. A file
            cannot be downloaded when its upload has not finished, when Metal
            could not process it, or when it is password-protected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
              example:
                code: 400
                message: file is not available to read (status ERROR)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            No file you can read has this ID. Metal returns this response when
            the ID does not exist, when the file belongs to another
            organization, and when the user who created the API key cannot read
            the file. Metal also returns 404 with the message `Unable to find
            file contents` when the file record exists but its stored contents
            are missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
              example:
                code: 404
                message: data entity not found
        '502':
          description: >-
            Metal could not read the file from storage or could not create the
            link. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
              example:
                code: 502
                message: failed to read file from storage
components:
  schemas:
    DocumentDownloadUrl:
      type: object
      description: A short-lived link to the original file that was uploaded to Metal.
      properties:
        url:
          type: string
          format: uri
          description: >-
            The download link. Anyone who has the link can download the file
            until it expires.
          example: https://files.example.com/acme-industrials-cim.pdf?signature=example
        filename:
          type: string
          description: The file name to save the download as.
          example: Acme Industrials CIM.pdf
        expiresAt:
          type: string
          format: date-time
          description: When the link expires, one hour after Metal issued it.
          example: '2026-01-15T15:04:05Z'
    CodedError:
      type: object
      description: >-
        An error that some endpoints return with the HTTP status code in the
        body.
      properties:
        code:
          type: integer
          description: The HTTP status code.
          example: 404
        message:
          type: string
          description: A human-readable error message.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
  responses:
    Unauthorized:
      description: Missing or invalid API key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid api key or clientId
  securitySchemes:
    MetalClientId:
      type: apiKey
      in: header
      name: x-metal-client-id
      description: The Client ID of your API key.
      x-default: <client-id>
    MetalApiKey:
      type: apiKey
      in: header
      name: x-metal-api-key
      description: The secret value of your API key.
      x-default: <api-key>

````

## Related topics

- [Get documents by ids](https://docs.metal.ai/api-reference/documents/get-documents-by-ids.md)
- [Search companies, deals, people, documents, and activities](https://docs.metal.ai/guides/search.md)
- [Search documents](https://docs.metal.ai/api-reference/documents/search-documents.md)
- [MCP tools reference](https://docs.metal.ai/mcp/tools-reference.md)
- [Microsoft Exchange integration: mail, calendar, contacts](https://docs.metal.ai/help/integrations/exchange.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.