Retrieve a Report via the API

Note: Broadsign Ads Scheduled Reports are created through the Broadsign Ads UI. You can then retrieve the reports through the Broadsign Ads Reports API endpoints.

This page describes how to retrieve a report The report contains all the dimensions and metrics information that you need to see. via the Broadsign Ads API. It assumes that you have already created at least one report in the Broadsign Ads UI, as described in Create a Scheduled Report via the UI.

To retrieve a report via the API:

  1. Get your API authorization token by accessing https://api.buy.broadsign.com/v1/auth with the following data:
    2. Copy 
    POST https://api.buy.broadsign.com/v1/auth
    {
      "Username": "myusername",
      "Password": "mypassword"
    }

    Replace the Username and Password with your own.

    The Broadsign Ads REST API will return the following data:

    Copy 
    {
        "token": "mytoken"
    }

    You will use this token A token is a piece of data that has no meaning or use on its own, but combined with the correct tokenization system, becomes a vital player in securing your application. Token based authentication works by ensuring that each request to a server is accompanied by a signed token which the server verifies for authenticity and only then responds to the request. as the authorization bearer in the header in the following steps.

    For more information, see Getting Your Authorization Token.

  2. Use the GET organizations method to fetch the list of Organizations In Broadsign Ads, an Organization is a client account that contains one or several users. to which you belong. Use your token set as the authorization bearer.
    3. Copy 
    GET https://api.buy.broadsign.com/v1/organizations
    {
      Authorization: [my token]
    }

    The Broadsign Ads REST API will return the list of Organizations to which you belong, for example:

    Copy 
    [
      {
        id: 123,
        name: "organization1"
      },
      {
        id: 234,
        name: "organization2"
      },
    ]

    For more information, see List Organizations.

  3. Use the GET reports method and the OrganizationId for the specific organization for which you want to fetch reports ("1234" in this example) in the URL of your request. Use your token set as the authorization bearer.
    4. Copy 
    GET https://api.buy.broadsign.com/v1/organizations/1234/reports
    {
      Authorization: Token [my token]
    }

    This will return a list of reports available for your organization, for example:

    Copy 
    [
      {
        id: 1001,
        name: "weekly impressions",
        latestExport: null
      },
      {
        id: 1002,
        name: "daily media cost",
        latestExport: {
          id: 567,
          generatedOn: "2022-09-21T21:13:01.930031+00:00",
          status: "Done"
      },
    ]

    Note: The status value in the response for the report must be "Done", or you will not be bale to fetch available exports.

    For more information, see List Reports.

  4. Use the GET exports method and the reportId for the specific report ("9876" in this example) that you want to fetch. Use your token set as the authorization bearer.
    5. Copy 
    GET https://api.buy.broadsign.com/v1/organizations/1234/reports/9876/exports
    {
      Authorization: [my token]
    }

    This will return a list of available exports An export represents one version of a generated report. for this report, for example:

    Copy 
    [
      {
        id: 568,
        generatedOn: "2022-09-22T21:13:01.930031+00:00",
        status: "Processing"
      },
      {
        id: 567,
        generatedOn: "2022-09-21T21:13:01.930031+00:00",
        status: "Done"
      },
      {
        id: 564,
        generatedOn: "2022-09-20T21:13:01.930031+00:00",
        status: "Failed"
      },
    ]

    For more information, see List Report Exports.

  5. Set the exportId for the specific report ("18219" in this example) export file The export file is the .csv file resulting from the report export operation. that you wish to download You can download the export file.. Use your token set as the authorization bearer.
    6. Copy 
    GET https://api.buy.broadsign.com/v1/organizations/1234/reports/9876/exports/18219/file
    {
      Authorization: [my token]
    }

    This will return the report in CSV format, for example:

    Copy 
    OrganizationId,Ads Played,Total Media Cost,Media Cost,Impressions
    123,3535000,596019,719053,121651000

    For more information, see Download Report Exports CSV.