# How to Generate Report Downloads

https://api-docs.lumar.io/docs/graphql/generate-report-downloads

Report downloads are CSV or XML files generated from the report.

Generating and getting Report Download files using API is done in 3 steps:

## Step 1: Create Report Download

Use the `createReportDownload` mutation to create a download and start the generation process.

As an input to define which report you want to generate a download from you can pass either `reportId`
or fields that describe the report: `crawlId`, `reportTemplateCode`, [`reportTypeCode`](/docs/schema/enums/report-type-code.md), and optionally a `segmentId`.
For a list of available report template codes please refer to the `Report templates` section of this documentation.

By default generated file will have all default report metrics. To select only a specific set of metrics pass an array
of selected metric codes in the `selectedMetrics` property.

To get the filtered set of report rows use the `filter` property which can take any `JSONObject`
and works for all datasources, but is only validated after mutation is submitted. There are also strongly typed
filter properties for each of the datasources that you can use instead of a generic filter. Explore
[`CreateReportDownloadInput`](/docs/schema/inputs/create-report-download-input.md) to see all available fields.
To know which datasource filter to use, you can get datasource code from a report or report template query.
For help with building filter queries go to [`filtering`](/docs/graphql/filtering.md) overview page.

```graphql
mutation CreateReportDownload($input: CreateReportDownloadInput!) {
  createReportDownload(input: $input) {
    reportDownload {
      ...ReportDownloadDetails
    }
  }
}

fragment ReportDownloadDetails on ReportDownload {
  id
  status
  outputType
  # ...other fields you want to retrieve
}
```

**Variables:**
```json
{
  "input": {
    "crawlId": "TjAwNUNyYXdsMTc2NjI0MQ",
    "reportTemplateCode": "all_pages",
    "reportTypeCode": "Basic",
    "selectedMetrics": ["url", "httpStatusCode"],
    "fileName": "url-error-status-codes",
    "filter": { "httpStatusCode": { "ge": 500 } }
  }
}
```

**Response:**
```json
{
  "data": {
    "createReportDownload": {
      "reportDownload": {
        "id": "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3",
        "status": "Generating",
        "outputType": "CsvZip"
      }
    }
  }
}
```

## Step 2: Wait for Report Download to generate

At first Report Download status will be `Generating`. When it's ready it'll change to `Generated`.

Depending on the size of the data in the report it may take from a few seconds to a few minutes to generate the file.

## Step 3: Get the Report Download

Use the `node` query to get the created Report Download

```graphql
query GetReportDownload {
  node(id: "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3") {
    ... on ReportDownload {
      status
      fileURL
      crawl{
        id
      }
    }
  }
}
```

**Response:**
```json
{
  "data": {
    "node": {
      "status": "Generated",
      "fileURL": "https://ds-reportexp-s3-exportedreportsbucket-resources-staging-use1.s3.us-east-1.amazonaws.com/ReportDownload-758687/http-only-chris24-co-uk_20-06-2024_All_Pages_basic.csv.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIARIBNDXU5VYYNWS4N%2F20240620%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240620T100045Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEJr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQC%2FvAWf8FUlqcYK5K%2FtcyxSi%2BZal3Yu%2B20d%2FNWZq0elTgIgbgIEHYE6tA%2B%2FGSoOM7vMVKbPuBp5gnrh6nLbbkKDlW4qwwQIQhADGgwwODU5OTM5NjI4MTEiDKmMNkA5BaiuOoGLDSqgBCOYudchkFAVi9sgECMkRj9AnyrWpiJCroOcMfxFmxCDHPM8oFLS4ze%2BpaOZeI9TsJqevfv1%2B0YIV2IZi5wmy3SKOiVJOmZynXc%2BGIVzlbotdE1U7%2BN5Nlbaf0bfKUHAZpfbbE2P8zA6P0bF5n6%2Bhp5TxnE4WjIjYm4rSW2tcTqF6HBq0e9Rh5bCFu32M%2FqfghZi6Ke5cKmjJwbRUdepwEkOPvQRiZ5FqaRJT3OC72P4mu8Xy96gmo77pv5cidCPMYwz1HQ2lwmzK%2FcUaJdDDaX%2F2dxVlBQoXoXlHepvNHmMbEXYZedurO1DUo%2FSLHUExkPa9xjo96Uvuw4hAuF1xFDg9l%2FfrUsixYdVLPq2Ojt6abjN%2FIxSf3dXCElN5aqdE%2B6ernGEfBtQIMQW34ut0yP7tbje4OCuF5pxlTU2I3JnI44eYfzzf8SQVeW%2FyALTNQpO4WayKR4%2FOOyz2bTZ%2Flt2%2BB7DvknrhxJIEoGRM1XQaen82mZlgijsxPppUptOUMU5IFlbH4VQ%2Fg7SD9v5jNz0Yp1w%2FBm88Z7DZ08SFo5JF4OKB0p0d7vpILxWaO%2BL2m7suNLIR5Im5UuoMCJtiGkneKrWn9JR43dJzXGjhxAdJLxwVcRxoe%2FsVyufgPcHHGr9yn66PZBXfcATZMQSphQ7TrATYS8w7KxTBRaOZYqPk7HHZJtMmhl%2BHc13r5LuszWuLNwO6P4%2Fukx1GM3qbnkwuerPswY6pgG3spEdD4%2FAYlEt77cFKbuKQNRE9nxVAu8heyO2f8lqwHCQt6tiJiMxcYGatsbRmIT85bpy3BzR0CHoTZdSn7gnqnVwGmmwfyOlyza3IJag0y1xuj8wQHR7onDHursPzUofldGzKMw4Cnu5tlxp0Ovuy1TNWh7hcGSXFgrpVwvMcbaTvVeQIW3%2B%2Ft3ela1foyp2Sa1yUuhWf3L%2Fwo4B4xy%2B6Cy6Nhu8&X-Amz-Signature=3984974e0dd7e8a68294fe4bddc8b32db92e991e39fbedab823b1ab92e3d2c06&X-Amz-SignedHeaders=host&x-id=GetObject",
      "crawl": {
        "id": "TjAwNUNyYXdsMTc2NjI0MQ"
      }
    }
  }
}
```

Use the `getCrawl` query to get all the Report Downloads for a crawl.

```graphql
query GetReportDownloads {
  getCrawl(id: 1234) {
    reportDownloads(
      first: 5
    ) {
      nodes {
        id
        status
        fileURL
      }
    }
  }
}
```

**Response:**
```json
{
  "data": {
    "getCrawl": {
      "reportDownloads": {
        "nodes": [
          {
            "id": "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3",
            "status": "Generated",
            "fileURL": "https://ds-reportexp-s3-exportedreportsbucket-resources-staging-use1.s3.us-east-1.amazonaws.com/ReportDownload-758687/http-only-chris24-co-uk_20-06-2024_All_Pages_basic.csv.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIARIBNDXU54S5EDTMA%2F20240620%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240620T084006Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEJj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQDs4S%2Fdam8ke54fgeORA05ilY8OvGsocUeVy4IX9BHEOAIgNoi8U%2F9gVJx0C41EPbgJoBdqGX%2BS%2ByeQ7PIrfwDoS4YqwwQIQRADGgwwODU5OTM5NjI4MTEiDLf%2FcnIqNYtsX89jOSqgBDLzJNXYwRoGr01l%2FL8tmwULT9fHfJm9jpldQPr25hlQCQm%2F1WEDwnd4dtzE7rNMgyQ8X7En2JrcM1TAqCiKbu%2B4KSFRJSMiuLn8IvCBQNaNWUmygWvlLXS7wMxPTjtl52zePYarhyfTVhqyFUqz75O8SHkim5WZCfSOexxkvBz2kvKaByPUOu6G4dG1%2FhaUg0XI2%2B1ZmcrWt58elHMoPuJL4Ma%2FvaZzfAGvt6DfQMBA%2FIAHd8JPDVJ4vuTIcjLmSVKwuV4MT4SWKXJ4IPIh%2BCeRg52UVh%2FMV7KexRH6nuhn3OPLtlMGZ1xTVzbzQl1ht1TLzM3qcpAozhRUMJudldUXXhVarxGy1O%2FXva8of9GazNNvQbC5ZCXJpyjN2h8KEsemXq9VuiJhtkhpD%2FzEDvHgW0HDSgww3MVd00qKBVJxeCr3vJETF7X8VPYMZE3Z%2BLaZWnYAhxi9VVy5dsL%2BHW1sZhPopnQQ8VuV3N1zdrSSMAr1q2qQF3VaUZLEZuQ73wUscAlNomYFc3xWkOb1HEOYNA8wg3Fqw1N0rfK30eAYqr3ilT0Hob4VdAyNekweVCamjY7lcedK%2BNNLQEtU5MrXzxeC6LFP2II9fJvtunh7ND8znkXq0%2BEYUl6tiVK8D3S8c48PGgwh7CsGN4jFVWV%2FU9FZwqpzu%2FO4cw3vY3HcYN%2BmoRgUOZGMbnZ80Ny8gTgYiZ3HsalgbDyUp2HQm%2F0wkMTPswY6pgHmEefyWpqG0bwG5ITaCsrW0XtoBnjp%2FeJdDwWAI400lNDDNzV1kvZWHCGuVAQi9RM049faxLMrHP38TxFifMspMYCcQxRz1nfrDUkUldB7HWqodkFp2a9R9qkmFtkMfl3eRgXONyHtO9HtrHCCnG3E%2B6bnLa%2F4smxa3HSQJlHVi5H22y6Ucwr0rk5uJIXtFJvivcCC9HWUfm8nejAmHxRvHA47Et4v&X-Amz-Signature=0a67804bed644bedc95799d5ff30bdf7785b7d9093207202532d3bc009e8a3eb&X-Amz-SignedHeaders=host&x-id=GetObject"
          }
        ]
      }
    }
  }
}
```

The response contains authenticated links to download the requested files. The links are valid for 7 days from the time they are generated, so data should be downloaded promptly.