{"_id":"57856c2287c9280e00903a62","parentDoc":null,"project":"55faf11ba62ba1170021a9a7","user":"5613e4f8fdd08f2b00437620","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":37,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"55faf9aa17b9d00d00969f49","pages":["56312d239ead230d00a188f2","56312e0d82d96a0d00b0fb08","56315777fc94aa0d00e9b553","56315b779ead230d00a1894a","5631657c9c25801700dac34f","56317884fc94aa0d00e9b586","56318386c3b04b0d00ba9bb9","563240ccdcc27a170082363b","563240dfbddb091700ad5e82","563240edfe9acd1900cc1d10","56324504fa40240d007c8d5f","56324b30c3b04b0d00ba9c96","563273ae45f2cb0d006be3fa","563273c08c9cda0d0025266d","563273cc38f8aa0d00d30f55","563273d838f8aa0d00d30f59","5632740945f2cb0d006be3fc","56327411df556c0d00cd0905","5632741b8c9cda0d0025266f","563274ea10b6040d008793d8","5632757cdf556c0d00cd0908","563275b710b6040d008793da","563275f938f8aa0d00d30f60","5632762fb904a10d0032f6fc","5632767110b6040d008793dd","563276c0b904a10d0032f700","5632770162c48a0d00334d53","5632843d8c9cda0d00252698","5632846e62c48a0d00334d78","56328a7e49e16d0d00122420","56328aaf49e16d0d00122425","56328b2238f8aa0d00d30f88","56328b6c8c9cda0d002526a2","56328c0710b6040d008793ff","56328c3710b6040d00879401","56328c5938f8aa0d00d30f8c","56328c90b904a10d0032f722","56328cc449e16d0d0012242a","56328ce68c9cda0d002526a8","56328d1338f8aa0d00d30f8e","56328d5810b6040d00879407","56328d7cdf556c0d00cd092f","56328d9a10b6040d00879409","56328db438f8aa0d00d30f92","56328dd762c48a0d00334d8b","56328df649e16d0d0012242d","56328e1edf556c0d00cd0931","56328e4662c48a0d00334d8e","56328e5edf556c0d00cd0933","56328e8f8c9cda0d002526ab","56328eb3b904a10d0032f72a","56328edb38f8aa0d00d30f95","56328ef210b6040d0087940d","56328f148c9cda0d002526ad","56328f2962c48a0d00334d90","56328f54b904a10d0032f72c","56328f6c38f8aa0d00d30f98","56328f858c9cda0d002526af","56328fae62c48a0d00334d95","56328fd838f8aa0d00d30f9c","5637f069ee0ee60d0024ec18","5641ffaa9417b40d00c0fc35","564355240d9748190079dea9","5644cfeb2c74cf1900da4831","56450f856b0ca50d00f6bd8f","56706537cbb2fb0d00f7c7dd","567065bc3d29830d00376213","56706fc2cbb2fb0d00f7c87e","568bf5a1e662f40d00eee866","568c0699e662f40d00eee881","568cff0274c77f2d00d56d51","568d10f58602880d001ce277","568d2abc37b636250036b904","568d343413c5ad0d00b34efb","568d593a8602880d001ce2d3","568e64135e12fb0d00325160","568e66f05e12fb0d00325162","568e78aa5e12fb0d0032517a","569433cfd8c04d1700e5ae0c","56943723d8c04d1700e5ae14","5694393b3e9d080d00f0655d","5694e6cf953b810d008f91bc","5694f301c5c5ce0d00058e68","569502ef9797fa1900f704e7","5695063bcaa32519009c40b3","569511cccaa32519009c40d9","569557e2fcb1032d0089dfe2","569562fefcb1032d0089dfee","56956428fe18811700c9c058","569639b87596a90d0014e5a3","56a90197e590350d004b5103","56a9021e9ec7660d002e08c2"],"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","__v":92,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-17T17:34:34.937Z","from_sync":false,"order":26,"slug":"api","title":"API Reference"},"__v":4,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-12T22:16:02.287Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"post","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":true,"order":91,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Advance Access\",\n  \"body\": \"This request contains an Advance Access parameter, `copy_only`. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.\\n\\nAs we haven't fully integrated it in our main API branch, there might be slight changes to the paths or parameter names. If you are a software developer, think \\\"beta access\\\" but with fewer expected bugs.\\n\\nWe are confident, however, that the feature is ready for use by our customers and partners who are willing to slightly modify their scripts at a later date.\"\n}\n[/block]\nThis call lets you queue a job to export a file from a project on the CGC into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the CGC. The volume you are exporting to must be configured for read-write access. To do this, set the `access_mode` parameter to `RW` when [creating](doc:create-a-volume-v2) or [modifying](doc:update-a-volume-v2) a volume.\n\nEssentially, the call writes to your cloud storage bucket on Amazon Web Services or Google Cloud Storage via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the CGC and, if no more copies of this file exist, it will no longer count towards your total storage price on the CGC. In summary, once you export a file from the CGC to a volume, it is no longer part of the storage on the CGC and cannot be exported again.\n\nLearn more about using the Volumes API for [Amazon S3](aws-cloud-storage-tutorial) and for [Google Cloud Storage](google-cloud-storage-tutorial).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cgc-api.sbgenomics.com/v2/storage/exports\",\n      \"language\": \"text\",\n      \"name\": \"Path\"\n    }\n  ]\n}\n[/block]\n##Request\n\n###Header Fields\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Description of value\",\n    \"0-0\": \"`X-SBG-Auth-Token`\\n_required_\",\n    \"0-1\": \"Your CGC [authentication token](doc:get-your-authentication-token).\",\n    \"h-2\": \"\",\n    \"1-0\": \"`Content-type`\\n_required_\",\n    \"1-1\": \"`application/json`\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n###Query parameters\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`overwrite`\",\n    \"0-1\": \"Boolean\",\n    \"0-2\": \"If true and a file exists in the given location on the volume (respecting volume prefix if given), the API will attempt to delete the existing file on the volume before exporting.\\n\\n_default_: `false`\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n###Query parameters - Advance Access\nThe following parameter is Advance Access. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`copy_only`\",\n    \"0-1\": \"Boolean\",\n    \"0-2\": \"If `true`, file will be copied to a volume but source file will remain on the Platform.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n###Request body\nIn the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`source`\\n_required_\",\n    \"0-1\": \"Object\",\n    \"1-0\": \"`file`\\n_required_\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The ID of the file for export.\",\n    \"2-0\": \"`destination`\\n_required_\",\n    \"2-1\": \"Object\",\n    \"3-0\": \"`volume`\\n_required_\",\n    \"3-1\": \"String\",\n    \"3-2\": \"The ID of the volume to which the file will be exported.\",\n    \"4-0\": \"`location`\\n_required_\",\n    \"4-1\": \"String\",\n    \"4-2\": \"Volume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file.\\n\\nPlease note that if this volume has been configured with a `prefix` parameter, the value of `prefix` will be prepended to `location` before attempting to create the file on the volume.\",\n    \"5-0\": \"`properties`\",\n    \"5-1\": \"Object\",\n    \"5-2\": \"Service-specific properties of the export.\\n\\nThese values override the defaults from the volume.\",\n    \"6-0\": \"`sse_algorithm`\",\n    \"6-1\": \"String\",\n    \"6-2\": \"S3 server-side encryption to use when exporting to this bucket.\\n\\nSupported values:\\n  * `AES256` (SSE-S3 encryption);\\n  * null (no server-side encryption).\\n\\n_default: `AES256`_\",\n    \"7-0\": \"`aws_canned_acl`\",\n    \"7-1\": \"String\",\n    \"7-2\": \"S3 canned ACL to apply on the object on during export.\\n\\nSupported values:\\n  * any one of [S3 canned ACLs](http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl);\\n  * `null` (do not apply canned ACLs).\\n\\n_default: `null`_.\",\n    \"0-2\": \"This object should describe the source from which the file should be exported.\",\n    \"2-2\": \"This object should describe the destination to which the file will be exported.\"\n  },\n  \"cols\": 3,\n  \"rows\": 8\n}\n[/block]\n##Example Request (normal)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v2/storage/exports HTTP/1.1\\nHost: cgc-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\\nContent-Type: application/json\",\n      \"language\": \"http\",\n      \"name\": null\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"destination\\\":{ \\n    \\\"volume\\\":\\\"rfranklin/output\\\",\\n    \\\"location\\\":\\\"output.vcf\\\"\\n },\\n  \\\"source\\\":{\\n      \\\"file\\\":\\\"58bf04c81c94ccab8329da13\\\"\\n  },\\n  \\\"overwrite\\\":false\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Example request (Advance Access - copy file only)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v2/storage/exports?copy_only=true HTTP/1.1\\nHost: cgc-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"destination\\\":{ \\n    \\\"volume\\\":\\\"rfranklin/output\\\",\\n    \\\"location\\\":\\\"output.vcf\\\"\\n },\\n  \\\"source\\\":{\\n      \\\"file\\\":\\\"58bf04c81c94ccab8329da13\\\"\\n  },\\n  \\\"overwrite\\\":false\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Response\n\n[See a list of CGC-specific response codes that may be contained in the body of the response.](doc:api-status-codes) \n\n###Response body\n\nThe response object contains information about the status of the export job. The information is structured using the following key-value pairs:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`id`\",\n    \"0-1\": \"String\",\n    \"1-1\": \"String\",\n    \"1-0\": \"`state`\",\n    \"2-0\": \"`source`\",\n    \"2-1\": \"Object\",\n    \"3-0\": \"`destination`\",\n    \"3-1\": \"Object\",\n    \"4-0\": \"`result`\",\n    \"4-1\": \"Object\",\n    \"5-0\": \"`error`\",\n    \"5-1\": \"Object\",\n    \"0-2\": \"ID of this export job\",\n    \"1-2\": \"The state of this export job. Possible values are:\\n  * `PENDING`: the export is queued\\n  * `RUNNING`: the export is running\\n  * `COMPLETED`: the export has completed successfully\\n  * `FAILED`: the export has failed\",\n    \"2-2\": \"Export source, as passed when this job was started by the call to [Start an export job](doc:start-an-export-job-v2).\",\n    \"3-2\": \"Export destination, as passed when this job was started by the call to [Start an export job](doc:start-an-export-job-v2).\",\n    \"4-2\": \"File object that was [exported](get-file-details).\",\n    \"5-2\": \"In case of error in the export job, standard API error is returned here.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n###Example response body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"href\\\": \\\"https://cgc-api.sbgenomics.com/v2/storage/exports/2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn\\\",\\n  \\\"id\\\": \\\"2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn\\\",\\n  \\\"state\\\": \\\"PENDING\\\",\\n  \\\"source\\\": {\\n    \\\"file\\\": \\\"58bf04c81c94ccab8329da13\\\"\\n  },\\n  \\\"destination\\\": {\\n    \\\"volume\\\": \\\"rfranklin/output\\\",\\n    \\\"location\\\": \\\"output.vcf\\\"\\n  },\\n  \\\"started_on\\\": \\\"2016-06-15T19:17:39Z\\\",\\n  \\\"properties\\\": {\\n    \\\"sse_algorithm\\\": \\\"AES256\\\"\\n  },\\n  \\\"overwrite\\\": false\\n}\",\n      \"language\": \"json\",\n      \"name\": \"\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"start-an-export-job-v2","type":"endpoint","title":"Start an export job"}

postStart an export job


[block:callout] { "type": "warning", "title": "Advance Access", "body": "This request contains an Advance Access parameter, `copy_only`. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.\n\nAs we haven't fully integrated it in our main API branch, there might be slight changes to the paths or parameter names. If you are a software developer, think \"beta access\" but with fewer expected bugs.\n\nWe are confident, however, that the feature is ready for use by our customers and partners who are willing to slightly modify their scripts at a later date." } [/block] This call lets you queue a job to export a file from a project on the CGC into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the CGC. The volume you are exporting to must be configured for read-write access. To do this, set the `access_mode` parameter to `RW` when [creating](doc:create-a-volume-v2) or [modifying](doc:update-a-volume-v2) a volume. Essentially, the call writes to your cloud storage bucket on Amazon Web Services or Google Cloud Storage via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the CGC and, if no more copies of this file exist, it will no longer count towards your total storage price on the CGC. In summary, once you export a file from the CGC to a volume, it is no longer part of the storage on the CGC and cannot be exported again. Learn more about using the Volumes API for [Amazon S3](aws-cloud-storage-tutorial) and for [Google Cloud Storage](google-cloud-storage-tutorial). [block:code] { "codes": [ { "code": "https://cgc-api.sbgenomics.com/v2/storage/exports", "language": "text", "name": "Path" } ] } [/block] ##Request ###Header Fields [block:parameters] { "data": { "h-0": "Key", "h-1": "Description of value", "0-0": "`X-SBG-Auth-Token`\n_required_", "0-1": "Your CGC [authentication token](doc:get-your-authentication-token).", "h-2": "", "1-0": "`Content-type`\n_required_", "1-1": "`application/json`" }, "cols": 2, "rows": 2 } [/block] ###Query parameters [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description of value", "0-0": "`overwrite`", "0-1": "Boolean", "0-2": "If true and a file exists in the given location on the volume (respecting volume prefix if given), the API will attempt to delete the existing file on the volume before exporting.\n\n_default_: `false`" }, "cols": 3, "rows": 1 } [/block] ###Query parameters - Advance Access The following parameter is Advance Access. This means that, while it is fully operational, it is subject to change. Learn more about this feature below. [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description", "0-0": "`copy_only`", "0-1": "Boolean", "0-2": "If `true`, file will be copied to a volume but source file will remain on the Platform." }, "cols": 3, "rows": 1 } [/block] ###Request body In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table. [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description of value", "0-0": "`source`\n_required_", "0-1": "Object", "1-0": "`file`\n_required_", "1-1": "String", "1-2": "The ID of the file for export.", "2-0": "`destination`\n_required_", "2-1": "Object", "3-0": "`volume`\n_required_", "3-1": "String", "3-2": "The ID of the volume to which the file will be exported.", "4-0": "`location`\n_required_", "4-1": "String", "4-2": "Volume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file.\n\nPlease note that if this volume has been configured with a `prefix` parameter, the value of `prefix` will be prepended to `location` before attempting to create the file on the volume.", "5-0": "`properties`", "5-1": "Object", "5-2": "Service-specific properties of the export.\n\nThese values override the defaults from the volume.", "6-0": "`sse_algorithm`", "6-1": "String", "6-2": "S3 server-side encryption to use when exporting to this bucket.\n\nSupported values:\n * `AES256` (SSE-S3 encryption);\n * null (no server-side encryption).\n\n_default: `AES256`_", "7-0": "`aws_canned_acl`", "7-1": "String", "7-2": "S3 canned ACL to apply on the object on during export.\n\nSupported values:\n * any one of [S3 canned ACLs](http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl);\n * `null` (do not apply canned ACLs).\n\n_default: `null`_.", "0-2": "This object should describe the source from which the file should be exported.", "2-2": "This object should describe the destination to which the file will be exported." }, "cols": 3, "rows": 8 } [/block] ##Example Request (normal) [block:code] { "codes": [ { "code": "POST /v2/storage/exports HTTP/1.1\nHost: cgc-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\nContent-Type: application/json", "language": "http", "name": null } ], "sidebar": true } [/block] [block:code] { "codes": [ { "code": "{\n \"destination\":{ \n \"volume\":\"rfranklin/output\",\n \"location\":\"output.vcf\"\n },\n \"source\":{\n \"file\":\"58bf04c81c94ccab8329da13\"\n },\n \"overwrite\":false\n}", "language": "json" } ] } [/block] ##Example request (Advance Access - copy file only) [block:code] { "codes": [ { "code": "POST /v2/storage/exports?copy_only=true HTTP/1.1\nHost: cgc-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"destination\":{ \n \"volume\":\"rfranklin/output\",\n \"location\":\"output.vcf\"\n },\n \"source\":{\n \"file\":\"58bf04c81c94ccab8329da13\"\n },\n \"overwrite\":false\n}", "language": "json" } ] } [/block] ##Response [See a list of CGC-specific response codes that may be contained in the body of the response.](doc:api-status-codes) ###Response body The response object contains information about the status of the export job. The information is structured using the following key-value pairs: [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description of value", "0-0": "`id`", "0-1": "String", "1-1": "String", "1-0": "`state`", "2-0": "`source`", "2-1": "Object", "3-0": "`destination`", "3-1": "Object", "4-0": "`result`", "4-1": "Object", "5-0": "`error`", "5-1": "Object", "0-2": "ID of this export job", "1-2": "The state of this export job. Possible values are:\n * `PENDING`: the export is queued\n * `RUNNING`: the export is running\n * `COMPLETED`: the export has completed successfully\n * `FAILED`: the export has failed", "2-2": "Export source, as passed when this job was started by the call to [Start an export job](doc:start-an-export-job-v2).", "3-2": "Export destination, as passed when this job was started by the call to [Start an export job](doc:start-an-export-job-v2).", "4-2": "File object that was [exported](get-file-details).", "5-2": "In case of error in the export job, standard API error is returned here." }, "cols": 3, "rows": 6 } [/block] ###Example response body [block:code] { "codes": [ { "code": "{\n \"href\": \"https://cgc-api.sbgenomics.com/v2/storage/exports/2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn\",\n \"id\": \"2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn\",\n \"state\": \"PENDING\",\n \"source\": {\n \"file\": \"58bf04c81c94ccab8329da13\"\n },\n \"destination\": {\n \"volume\": \"rfranklin/output\",\n \"location\": \"output.vcf\"\n },\n \"started_on\": \"2016-06-15T19:17:39Z\",\n \"properties\": {\n \"sse_algorithm\": \"AES256\"\n },\n \"overwrite\": false\n}", "language": "json", "name": "" } ], "sidebar": true } [/block]