# Export
Endpoints for working with bulk data exports: create a new export, look up the status of an existing export, download a completed export, and list recent exports.
## Create an Export
> Creates an asynchronous export request. The export is queued and processed in the background; the response returns the export's \`id\` and an initial \`status\` of \`PENDING\`.\
> \
> Store the returned \`id\` so you can look up the export's status or download it once complete. For details on the export lifecycle and how to detect completion, see the Export Overview.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Export","version":"1.0.0"},"tags":[{"name":"Export","description":"Endpoints for working with bulk data exports: create a new export, look up the status of an existing export, download a completed export, and list recent exports.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions."}},"schemas":{"ExportStub":{"description":"Request body for creating a new export.","required":["type"],"properties":{"type":{"description":"The type of Export that's being requested.","type":"string","enum":["USER","USER_REFERRAL","REFERRAL","USER_REWARD_BALANCE","REWARD_BALANCE","REWARD"]},"format":{"description":"The format of the Export","type":"string","default":"CSV","enum":["CSV","XLSX"]},"name":{"description":"A user-friendly name for this report. Useful for keeping track of which report is which.","type":"string"},"requester":{"description":"Detail on the service or user that requested this report. Defaults to `\"API\"` when not provided.","type":"string","default":"API"},"params":{"description":"Filter parameters for limiting the records returned. Multiple parameters are combined with a logical AND.","type":"object","nullable":true,"properties":{"createdSince":{"description":"Filters for results **created since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"createdBefore":{"description":"Filters for results **created before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"updatedSince":{"description":"Filters for results **updated since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"updatedBefore":{"description":"Filters for results **updated before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedSince":{"description":"Filters for results **created or updated since this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedBefore":{"description":"Filters for results **created or updated before this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"programId":{"description":"The ID of the program that each user's share links and referral code should be populated from. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"string"},"filter":{"description":"A filter defining which rewards to export. See GraphQL `RewardFilterInput`. Works with `REWARD`.","type":"object"},"at":{"description":"Optional timestamp for exporting the rewards' states at a specific point in time. Works with `REWARD`.","type":"integer","format":"int64"},"fields":{"description":"Settings for which fields are included in the export.","type":"object","properties":{"includeUserStatsFields":{"description":"Whether user stats fields should be included. Works with `USER`.","type":"boolean","default":false},"includeUserFields":{"description":"Whether user fields should be included. Works with `REWARD`.","type":"boolean","default":false},"includeReferralFields":{"description":"Whether referral fields should be included. Works with `REWARD`.","type":"boolean","default":false}}}}}}},"Export":{"description":"An export record. Includes the original request fields plus the export's `id`, `status`, and timestamps.","allOf":[{"$ref":"#/components/schemas/ExportStub"},{"properties":{"id":{"description":"A unique ID used to track the export. Use this to look up the export's status or download it.","type":"string","readOnly":true},"mailtoEmail":{"description":"Email address to notify when the export completes. Null if not set.","type":"string","nullable":true,"readOnly":true},"status":{"description":"The current state of the export. `PENDING` while queued or running, `COMPLETED` when ready to download, `ABORTED` on unrecoverable error, and `EXPIRED` once the file is no longer available.","type":"string","readOnly":true,"enum":["PENDING","COMPLETED","ABORTED","EXPIRED"]},"dateCreated":{"description":"Unix timestamp (milliseconds) when the export was requested. Never changes.","type":"integer","format":"int64","readOnly":true},"dateCompleted":{"description":"Unix timestamp (milliseconds) when the export finished processing and `status` became `COMPLETED`.","type":"integer","format":"int64","nullable":true,"readOnly":true},"dateExpires":{"description":"Unix timestamp (milliseconds) when the export will expire and no longer be downloadable.","type":"integer","format":"int64","nullable":true,"readOnly":true}}}]},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine error code","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string","nullable":true}}}},"responses":{"GeneralError":{"description":"Unexpected Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/export":{"post":{"summary":"Create an Export","description":"Creates an asynchronous export request. The export is queued and processed in the background; the response returns the export's `id` and an initial `status` of `PENDING`.\n\nStore the returned `id` so you can look up the export's status or download it once complete. For details on the export lifecycle and how to detect completion, see the Export Overview.\n","operationId":"createExport","tags":["Export"],"parameters":[{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Details of the export to be created","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportStub"}}}},"responses":{"201":{"description":"Export created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"default":{"$ref":"#/components/responses/GeneralError"}}}}}}
```
## Lookup an Export
> Returns the current state of an export, including its \`status\`. Use this to poll for completion before attempting to download.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Export","version":"1.0.0"},"tags":[{"name":"Export","description":"Endpoints for working with bulk data exports: create a new export, look up the status of an existing export, download a completed export, and list recent exports.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions."}},"schemas":{"Export":{"description":"An export record. Includes the original request fields plus the export's `id`, `status`, and timestamps.","allOf":[{"$ref":"#/components/schemas/ExportStub"},{"properties":{"id":{"description":"A unique ID used to track the export. Use this to look up the export's status or download it.","type":"string","readOnly":true},"mailtoEmail":{"description":"Email address to notify when the export completes. Null if not set.","type":"string","nullable":true,"readOnly":true},"status":{"description":"The current state of the export. `PENDING` while queued or running, `COMPLETED` when ready to download, `ABORTED` on unrecoverable error, and `EXPIRED` once the file is no longer available.","type":"string","readOnly":true,"enum":["PENDING","COMPLETED","ABORTED","EXPIRED"]},"dateCreated":{"description":"Unix timestamp (milliseconds) when the export was requested. Never changes.","type":"integer","format":"int64","readOnly":true},"dateCompleted":{"description":"Unix timestamp (milliseconds) when the export finished processing and `status` became `COMPLETED`.","type":"integer","format":"int64","nullable":true,"readOnly":true},"dateExpires":{"description":"Unix timestamp (milliseconds) when the export will expire and no longer be downloadable.","type":"integer","format":"int64","nullable":true,"readOnly":true}}}]},"ExportStub":{"description":"Request body for creating a new export.","required":["type"],"properties":{"type":{"description":"The type of Export that's being requested.","type":"string","enum":["USER","USER_REFERRAL","REFERRAL","USER_REWARD_BALANCE","REWARD_BALANCE","REWARD"]},"format":{"description":"The format of the Export","type":"string","default":"CSV","enum":["CSV","XLSX"]},"name":{"description":"A user-friendly name for this report. Useful for keeping track of which report is which.","type":"string"},"requester":{"description":"Detail on the service or user that requested this report. Defaults to `\"API\"` when not provided.","type":"string","default":"API"},"params":{"description":"Filter parameters for limiting the records returned. Multiple parameters are combined with a logical AND.","type":"object","nullable":true,"properties":{"createdSince":{"description":"Filters for results **created since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"createdBefore":{"description":"Filters for results **created before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"updatedSince":{"description":"Filters for results **updated since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"updatedBefore":{"description":"Filters for results **updated before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedSince":{"description":"Filters for results **created or updated since this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedBefore":{"description":"Filters for results **created or updated before this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"programId":{"description":"The ID of the program that each user's share links and referral code should be populated from. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"string"},"filter":{"description":"A filter defining which rewards to export. See GraphQL `RewardFilterInput`. Works with `REWARD`.","type":"object"},"at":{"description":"Optional timestamp for exporting the rewards' states at a specific point in time. Works with `REWARD`.","type":"integer","format":"int64"},"fields":{"description":"Settings for which fields are included in the export.","type":"object","properties":{"includeUserStatsFields":{"description":"Whether user stats fields should be included. Works with `USER`.","type":"boolean","default":false},"includeUserFields":{"description":"Whether user fields should be included. Works with `REWARD`.","type":"boolean","default":false},"includeReferralFields":{"description":"Whether referral fields should be included. Works with `REWARD`.","type":"boolean","default":false}}}}}}},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine error code","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string","nullable":true}}}},"responses":{"GeneralError":{"description":"Unexpected Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/export/{exportId}":{"get":{"summary":"Lookup an Export","description":"Returns the current state of an export, including its `status`. Use this to poll for completion before attempting to download.","operationId":"getExport","tags":["Export"],"parameters":[{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}},{"name":"exportId","in":"path","description":"The `id` of the export to look up.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"404":{"description":"Export NOT found"},"default":{"$ref":"#/components/responses/GeneralError"}}}}}}
```
## Download an Export
> Downloads a completed export file. The export's \`status\` must be \`COMPLETED\`; use the lookup endpoint to confirm before calling this.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Export","version":"1.0.0"},"tags":[{"name":"Export","description":"Endpoints for working with bulk data exports: create a new export, look up the status of an existing export, download a completed export, and list recent exports.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions."}},"responses":{"GeneralError":{"description":"Unexpected Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine error code","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string","nullable":true}}}}},"paths":{"/{tenant_alias}/export/{exportId}/download":{"get":{"summary":"Download an Export","description":"Downloads a completed export file. The export's `status` must be `COMPLETED`; use the lookup endpoint to confirm before calling this.","operationId":"downloadExport","tags":["Export"],"parameters":[{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}},{"name":"exportId","in":"path","description":"The `id` of the export to download.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export file returned after following the redirect.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"303":{"description":"Redirect to the export file. Follow the `Location` header to download the CSV from the storage provider. Ensure your HTTP client is configured to follow redirects (e.g. `curl -L`).","headers":{"Location":{"description":"Signed URL to the export file on the storage provider. The URL expires after a short period.","schema":{"type":"string","format":"uri"}}}},"default":{"$ref":"#/components/responses/GeneralError"}}}}}}
```
## List Exports
> Returns a paginated list of exports in the tenant. Useful for finding a recent export when you don't have its \`id\`.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Export","version":"1.0.0"},"tags":[{"name":"Export","description":"Endpoints for working with bulk data exports: create a new export, look up the status of an existing export, download a completed export, and list recent exports.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions."}},"schemas":{"ExportList":{"description":"A paginated list of Export objects.","properties":{"data":{"type":"array","description":"The exports returned in this page.","items":{"$ref":"#/components/schemas/Export"}},"count":{"type":"integer","description":"The number of results in this page. See `totalCount` for the total available."},"totalCount":{"type":"integer","description":"The total number of results available across all pages."}}},"Export":{"description":"An export record. Includes the original request fields plus the export's `id`, `status`, and timestamps.","allOf":[{"$ref":"#/components/schemas/ExportStub"},{"properties":{"id":{"description":"A unique ID used to track the export. Use this to look up the export's status or download it.","type":"string","readOnly":true},"mailtoEmail":{"description":"Email address to notify when the export completes. Null if not set.","type":"string","nullable":true,"readOnly":true},"status":{"description":"The current state of the export. `PENDING` while queued or running, `COMPLETED` when ready to download, `ABORTED` on unrecoverable error, and `EXPIRED` once the file is no longer available.","type":"string","readOnly":true,"enum":["PENDING","COMPLETED","ABORTED","EXPIRED"]},"dateCreated":{"description":"Unix timestamp (milliseconds) when the export was requested. Never changes.","type":"integer","format":"int64","readOnly":true},"dateCompleted":{"description":"Unix timestamp (milliseconds) when the export finished processing and `status` became `COMPLETED`.","type":"integer","format":"int64","nullable":true,"readOnly":true},"dateExpires":{"description":"Unix timestamp (milliseconds) when the export will expire and no longer be downloadable.","type":"integer","format":"int64","nullable":true,"readOnly":true}}}]},"ExportStub":{"description":"Request body for creating a new export.","required":["type"],"properties":{"type":{"description":"The type of Export that's being requested.","type":"string","enum":["USER","USER_REFERRAL","REFERRAL","USER_REWARD_BALANCE","REWARD_BALANCE","REWARD"]},"format":{"description":"The format of the Export","type":"string","default":"CSV","enum":["CSV","XLSX"]},"name":{"description":"A user-friendly name for this report. Useful for keeping track of which report is which.","type":"string"},"requester":{"description":"Detail on the service or user that requested this report. Defaults to `\"API\"` when not provided.","type":"string","default":"API"},"params":{"description":"Filter parameters for limiting the records returned. Multiple parameters are combined with a logical AND.","type":"object","nullable":true,"properties":{"createdSince":{"description":"Filters for results **created since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"createdBefore":{"description":"Filters for results **created before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.","type":"integer","format":"int64"},"updatedSince":{"description":"Filters for results **updated since this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"updatedBefore":{"description":"Filters for results **updated before this date**. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedSince":{"description":"Filters for results **created or updated since this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"createdOrUpdatedBefore":{"description":"Filters for results **created or updated before this date**. Useful for incremental exports into a data warehouse. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"integer","format":"int64"},"programId":{"description":"The ID of the program that each user's share links and referral code should be populated from. Works with `USER`, `USER_REFERRAL`, `REFERRAL`.","type":"string"},"filter":{"description":"A filter defining which rewards to export. See GraphQL `RewardFilterInput`. Works with `REWARD`.","type":"object"},"at":{"description":"Optional timestamp for exporting the rewards' states at a specific point in time. Works with `REWARD`.","type":"integer","format":"int64"},"fields":{"description":"Settings for which fields are included in the export.","type":"object","properties":{"includeUserStatsFields":{"description":"Whether user stats fields should be included. Works with `USER`.","type":"boolean","default":false},"includeUserFields":{"description":"Whether user fields should be included. Works with `REWARD`.","type":"boolean","default":false},"includeReferralFields":{"description":"Whether referral fields should be included. Works with `REWARD`.","type":"boolean","default":false}}}}}}},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine error code","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string","nullable":true}}}},"responses":{"GeneralError":{"description":"Unexpected Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/export/history/list":{"get":{"summary":"List Exports","description":"Returns a paginated list of exports in the tenant. Useful for finding a recent export when you don't have its `id`.","operationId":"listExports","tags":["Export"],"parameters":[{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"A limit on the maximum number of results to return, defaults to `10`.","schema":{"type":"integer","default":10}},{"name":"offset","in":"query","description":"The row number of the first result to return, defaults to `0`.","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of Exports found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportList"}}}},"default":{"$ref":"#/components/responses/GeneralError"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/export-overview/export.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.