Reports

Overview

Reporting API enables users to create applications that can do the following:

  • Create report
  • Execute a report to generate a reportrun
  • Check the status of a reportrun
  • Retrieve the download URL for a completed report
  • Schedule a reportrun

  • This document provides operations to create, read, update, delete reports.

    Read Report

    The report data consists of dimensions and metrics. Metrics represent the user activity measurement eg. click, impressions etc. Dimensions break down metrics across some common criteria, such as country or browser.

    Permissions

    A user access token with Atlas API capability is required to request report details.

    Fields

    Reading this endpoint returns a single or an array of Report objects with the same fields as the node.

    Read Report

    You can get details of a report by making an HTTP GET request.

    An example of the request and response:

    Request:

    https://graph.facebook.com/v2.0/<REPORT_ID>
    

    Response:

    {
      "company_id": "11002200631700", 
      "created_date": "2013-11-07T01:01:18+0000", 
      "definition": {
        "column_definitions": [
          {
            "aggregation_usage": "dimension", 
            "area": "serving", 
            "category": "standard", 
            "description": "The name of ad.", 
            "incompatibilities": [
              {
                "category": "standard", 
                "key": "action_requests"
              }
            ], 
            "key": "ad_name", 
            "name": "Ad Name"
          }, 
          {
            "aggregation_usage": "metric", 
            "area": "serving", 
            "category": "standard", 
            "description": "The number of clicks delivered for the current row.", 
            "incompatibilities": [
              {
                "category": "standard", 
                "key": "action_requests"
              }, 
              {
                "category": "standard", 
                "key": "dpb_event_ts"
              }, 
              {
                "category": "standard", 
                "key": "dpb_category"
              }, 
              {
                "category": "standard", 
                "key": "dpb_hashed_cookie"
              }, 
              {
                "category": "standard", 
                "key": "dpb_ip_address"
              }, 
              {
                "category": "standard", 
                "key": "dpb_is_tentative"
              }, 
              {
                "category": "standard", 
                "key": "dpb_contributor_time"
              }, 
              {
                "category": "standard", 
                "key": "dpb_conversion_type"
              }, 
              {
                "category": "standard", 
                "key": "dpb_xdata"
              }, 
              {
                "category": "standard", 
                "key": "dpb_audience_id"
              }, 
              {
                "category": "standard", 
                "key": "dpb_audience_name"
              }, 
              {
                "category": "standard", 
                "key": "dpb_event_id"
              }, 
              {
                "category": "standard", 
                "key": "dpb_clickthrough_url"
              }, 
              {
                "category": "standard", 
                "key": "dpb_country"
              }, 
              {
                "category": "standard", 
                "key": "dpb_state"
              }
            ], 
            "key": "counters_clicks", 
            "name": "Clicks"
          }
        ], 
        "columns": [
          "ad_name", 
          "counters_clicks"
        ], 
        "date_range": {
          "date_unit": "", 
          "quantity": "0", 
          "time_zone": "America/New_York", 
          "type": "lifetime"
        }, 
        "filters": {
          "advertiser_ids": [
            "11002200631100"
          ], 
          "client_ids": [
            "11002200631300"
          ], 
          "include_tentative_cookies": false
        }, 
        "include_empty_metric_rows": false, 
        "report_type": "column_determined", 
        "time_zone": "America/New_York"
      }, 
      "description": "", 
      "email_suffix": "", 
      "file_format": "csv", 
      "id": "11002200631500", 
      "is_email_enabled": false, 
      "is_favorite": false, 
      "last_modified_date": "2013-11-07T01:01:18+0000", 
      "name": "Test Report", 
      "version": "3"
    }
    

    Curl Example

    A curl example to get company reports:

    curl -G \
      -d 'access_token=<ACCESS_TOKEN>' \
    https://graph.facebook.com/v2.0/<REPORT_ID>
    

    Read Company Reports

    You can get details of reports generated for a particular company by making an HTTP GET request.

    An example of the request and response:

    Request:

    https://graph.facebook.com/v2.0/<COMPANY_ID>/reports
    

    Response:

    {
      "data": [
        {
          "company_id": "11002200631700", 
          "created_date": "2013-11-07T01:01:18+0000", 
          "definition": {
            "column_definitions": [
              {
                "aggregation_usage": "dimension", 
                "area": "serving", 
                "category": "standard", 
                "description": "The name of ad.", 
                "incompatibilities": [
                  {
                    "category": "standard", 
                    "key": "action_requests"
                  }
                ], 
                "key": "ad_name", 
                "name": "Ad Name"
              }, 
              {
                "aggregation_usage": "metric", 
                "area": "serving", 
                "category": "standard", 
                "description": "The number of clicks delivered for the current row.", 
                "incompatibilities": [
                  {
                    "category": "standard", 
                    "key": "action_requests"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_event_ts"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_category"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_hashed_cookie"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_ip_address"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_is_tentative"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_contributor_time"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_conversion_type"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_xdata"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_audience_id"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_audience_name"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_event_id"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_clickthrough_url"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_country"
                  }, 
                  {
                    "category": "standard", 
                    "key": "dpb_state"
                  }
                ], 
                "key": "counters_clicks", 
                "name": "Clicks"
              }
            ], 
            "columns": [
              "ad_name", 
              "counters_clicks"
            ], 
            "date_range": {
              "date_unit": "", 
              "quantity": "0", 
              "time_zone": "America/New_York", 
              "type": "lifetime"
            }, 
            "filters": {
              "advertiser_ids": [
                "11002200631100"
              ], 
              "client_ids": [
                "11002200631300"
              ], 
              "include_tentative_cookies": false
            }, 
            "include_empty_metric_rows": false, 
            "report_type": "column_determined", 
            "time_zone": "America/New_York"
          }, 
          "description": "", 
          "email_suffix": "", 
          "file_format": "csv", 
          "id": "11002200631500", 
          "is_email_enabled": false, 
          "is_favorite": false, 
          "last_modified_date": "2013-11-07T01:01:18+0000", 
          "name": "Test Report", 
          "version": "3"
        }
      ]
    }
    

    Curl Example

    A curl example to get company reports:

    curl -G \
      -d 'access_token=<ACCESS_TOKEN>' \
    https://graph.facebook.com/v2.0/<COMPANY_ID>/reports
    

    Create Atlas Reports

    Permissions

    A user access token with Atlas API capability is required to create reports.

    Fields

    Publishing a report will create a single or array of Report objects with the same fields as the node.

    Create Report

    You can create report by making an HTTP POST request. These reports will be owned by the user. It will update the report if it already exists.

    An example of the request and response to create report:

    Request string endpoint:

    https://graph.facebook.com/v2.0/<COMPANY_ID>/reports?reports=[{"name": "Test Report", "version": null, "description": "",     "definition": {"report_type": "column_determined", "column_definitions": [         {"area": "serving", "attribution_model": null, "category": "standard",           "key": "ad_id","name": "Ad ID","aggregation_usage": "dimension" }, {           "area": "serving", "attribution_model": "last_touch", "category": "standard",           "key": "counters_clicks", "name": "Clicks", "aggregation_usage": "metric"         }], "date_range": {"type": "relative", "date_unit": "day", "quantity": "0",         "time_zone": "America/New_York" }, "time_zone": "America/New_York",     "filters": { "client_ids": ["11002200631300"],        "action_tag_attribution_filters": [] } }, "file_format": "xlsx",     "is_email_enabled": false, "email_addresses": [], "email_suffix": "" }]
    

    Response:

    {
      "data": [
        {
          "id": "11002200631500", 
          "success": true
        }
      ]
    }
    

    Curl Example

    A curl example to create a report:

    curl  \
      -F 'reports=[{"name": "Test Report", "version": null, "description": "", "definition": {"report_type": "column_determined", "column_definitions": [{"area": "serving", "attribution_model": null, "category": "standard", "key": "ad_id","name": "Ad ID","aggregation_usage": "dimension" }, {"area": "serving", "attribution_model": "last_touch", "category": "standard", "key": "counters_clicks", "name": "Clicks", "aggregation_usage": "metric" }], "date_range": {"type": "relative", "date_unit": "day", "quantity": "0", "time_zone": "America/New_York" }, "time_zone": "America/New_York","filters": { "client_ids": ["11002200631300"],        "action_tag_attribution_filters": [] } }, "file_format": "xlsx",     "is_email_enabled": false, "email_addresses": [], "email_suffix": "" }]' \
      -F 'access_token=<ACCESS_TOKEN>' \
    https://graph.facebook.com/v2.0/<COMPANY_ID>/reports
    

    Delete Atlas Reports

    You cannot delete atlas reports.

    Read ReportColumns

    The Report definition includes a columns parameter which is used to configure what data columns are to be included in the Report. Some example columns are advertiser_id, advertiser_name, counters_clicks, counters_impressions. In additon to these, there are certain incompatible columns when creating a report definition. Users cannot create certain combinations of report columns.

    Permissions

    A user access token with Atlas API capability is required to read reportcolumns.

    Fields

    Reading this endpoint returns a single or an array of Report Column objects with the same fields as the node.

    Read Company ReportColumns

    You can get report columns for a company by making an HTTP GET request.

    An example of the request and response:

    Request:

    https://graph.facebook.com/v2.0/<COMPANY_ID>/report_columns
    

    Response:

    {
      "data": [
        {
          "aggregation_usage": "metric", 
          "area": "attribution", 
          "attribution_model": "full_path", 
          "category": "standard", 
          "description": "Value of extended data metric 18 based on full path attribution.", 
          "incompatibilities": [
            {
              "category": "standard", 
              "key": "action_requests"
            },
            {
              "category": "standard", 
              "key": "dpb_event_ts"
            }, 
            {
              "category": "standard", 
              "key": "dpb_category"
            }, 
            {
              "category": "standard", 
              "key": "dpb_hashed_cookie"
            }, 
            {
              "category": "standard", 
              "key": "dpb_ip_address"
            }, 
            {
              "category": "standard", 
              "key": "dpb_is_tentative"
            }, 
            {
              "category": "standard", 
              "key": "dpb_contributor_time"
            }, 
            {
              "category": "standard", 
              "key": "dpb_conversion_type"
            }, 
            {
              "category": "standard", 
              "key": "dpb_xdata"
            }, 
            {
              "category": "standard", 
              "key": "dpb_audience_id"
            }, 
            {
              "category": "standard", 
              "key": "dpb_audience_name"
            }, 
            {
              "category": "standard", 
              "key": "dpb_event_id"
            }, 
            {
              "category": "standard", 
              "key": "dpb_clickthrough_url"
            }, 
            {
              "category": "standard", 
              "key": "dpb_country"
            }, 
            {
              "category": "standard", 
              "key": "dpb_state"
            }
          ], 
          "key": "action_metric_18_full_path", 
          "name": "Action Metric 18 - Even Credit"
        }
      ]
    }
    

    Curl Example

    A curl example to read reportcolumns for a company:

    curl -G \ 
      -d 'access_token=<ACCESS_TOKEN>' \
    https://graph.facebook.com/v2.0/<COMPANY_ID>/report_columns