How can we help?

Overview

The Audience Trends export resource creates an export job to download and store a file of audience trends data from the Cordial database. This endpoint is only available in the v2 API.

• API set name: audiencetrendsexport

Additional information

• This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host log in authentication information and the fields to include in the file.
• It is important to note that this resource is not a collection of exports, but is a resource that initiates export processing by creating an export job.
• Export status information is available through the jobs resource. You can access the Jobs page from the Cordial UI.
• Export supports file type CSV.
• Export files in the UI will be stored for 30 days from the date of the export.

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Methods, parameters, and examples

• POST/v2/audiencetrendsexport

POST/v2/audiencetrendsexport

• Parameters
• Example JSON requests
• Example request URL

* Required

UI

The following will initiate an export job of a CSV file containing a column for each day in the selected timeframe and a row for each audience in the audiences array. The file will be downloadable via the UI on the Jobs page.

{
  "name": "audiencetrends",
  "exportType": "csv",
  "destination": {
    "type": "aws"
  },
  "selected_timeframe_start": "2025-07-16",
  "selected_timeframe_end": "2025-08-16",
  "audiences": [
    "audience1","audience2"
  ]
}

SFTP

The following will initiate an export job of a CSV file via SFTP containing a column for each day in the selected timeframe and a row for each audience in the audiences array.

{
    "name": "audiencetrends",
    "exportType": "csv",
    "destination": {
        "type": "sftp",
        "server": "example.com",
        "port": "21",
        "username": "username",
        "password": "password",
        "path": "/"
    },
    "selected_timeframe_start": "2021-07-16",
    "selected_timeframe_end": "2021-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

Amazon S3

The following will initiate an export job of CSV file via Amazon S3. In this example, the file will be uploaded to s3://my_bucket/folder. The file will contain a column for each day in the selected timeframe and a row for each audience in the audiences array.

{
  "name": "audiencetrends",
  "exportType": "csv",
  "destination": {
    "type": "s3",
    "aws_access_key_id": "A1234567890",
    "aws_secret_access_key": "B1234567890",
    "aws_bucket": "my_bucket",
    "aws_region": "us-west-2",
    "path": "folder"
  },
  "selected_timeframe_start": "2021-07-16",
    "selected_timeframe_end": "2021-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

We recommend omitting the trailing slash right after your S3 path name to avoid duplicate slashes being added by default. For example, use folder instead of /folder/.

Google Cloud Storage

The following will initiate an export job of a CSV file via Google Cloud Storage (GCS). The file will contain a column for each day in the selected timeframe and a row for each audience in the audiences array.

Your Google Cloud Storage integration must be enabled.

{
    "name": "audiencetrends",
    "exportType": "csv",
    "destination": {
        "type": "gcs",
        "gcs_bucket": "bucketname",
        "path": "/audiencetrendsexport"
    },
    "selected_timeframe_start": "2025-07-16",
    "selected_timeframe_end": "2025-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

The following URL in conjunction with the JSON will perform the POST.

https://<path>/v2/audiencetrendsexport

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. You can find common errors on the Global API Error Responses page.