Skip to main content

How to 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, 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 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 overview page.

Operation: mutation CreateReportDownload($input: CreateReportDownloadInput!) { createReportDownload(input: $input) { reportDownload { ...ReportDownloadDetails } } } fragment ReportDownloadDetails on ReportDownload { id status outputType # ...other fields you want to retrieve }Variables: { "input": { "crawlId": "TjAwNUNyYXdsMTc2NjI0MQ", "reportTemplateCode": "all_pages", "reportTypeCode": "Basic", "selectedMetrics": ["url", "httpStatusCode"], "fileName": "url-error-status-codes", "filter": { "httpStatusCode": { "ge": 500 } } } }Response Example: { "data": { "createReportDownload": { "reportDownload": { "id": "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3", "status": "Generating", "outputType": "CsvZip" } } } }
CreateReportDownloadTry in Explorer
GraphQL
mutation CreateReportDownload($input: CreateReportDownloadInput!) {
  createReportDownload(input: $input) {
    reportDownload {
      ...ReportDownloadDetails
    }
  }
}

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

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

Operation: query GetReportDownload { node(id: "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3") { ... on ReportDownload { status fileURL crawl{ id } } } }Response Example: { "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" } } } }
GetReportDownloadTry in Explorer
GraphQL
query GetReportDownload {
  node(id: "TjAxNFJlcG9ydERvd25sb2FkNzU4Njg3") {
    ... on ReportDownload {
      status
      fileURL
      crawl{
        id
      }
    }
  }
}

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

Operation: query GetReportDownloads { getCrawl(id: 1234) { reportDownloads( first: 5 ) { nodes { id status fileURL } } } }Response Example: { "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" } ] } } } }
GetReportDownloadsTry in Explorer
GraphQL
query GetReportDownloads {
  getCrawl(id: 1234) {
    reportDownloads(
      first: 5
    ) {
      nodes {
        id
        status
        fileURL
      }
    }
  }
}

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.