Report Endpoints

Report [/v1/reports/{id}]

• Parameters
  • id (required, integer, 1): The identifier of the Report.
• Model (application/json)
  

  {
    "id": 1,
    "public_id": "628a3960-521a-11e3-8f96-0800200c9a66",
    "status": "completed",
    "urls": [
      "http://reporting.trader.adgear.com/public/123.csv.gz",
      "http://reporting.trader.adgear.com/public/456.tsv.zip"
    ],
    "secure_urls": [
      "https://reporting.trader.adgear.com/public/123.csv.gz",
      "https://reporting.trader.adgear.com/public/456.tsv.zip"
    ],
    "created_at": "2016-04-01T00:00:00Z",
    "updated_at": "2016-04-01T00:00:00Z",
    "author_id": 1,
    "author_name": "Json Smith",
    "title": "test title",
    "metadata": "{\"my_custom_property\":\"my_custom_value\"}",
    "query": {
      "type": "adgear_agency_delivery",
      "start_date": "2016-04-01T00:00:00Z",
      "end_date": "2016-04-07T23:59:59Z",
      "dimensions": ["campaign_id"],
      "metrics": ["impressions"],
      "filter": "campaign_id = 52",
      "order_fields": ["campaign_id", "-impressions"],
      "limit": 1,
      "offset": 0
    },
    "notification": {
      "emails": ["json.smith@gmail.com"],
      "http_callbacks": ["http://my.callback.com/"]
    },
    "report_url": "http://reporting.trader.adgear.com/reports/1",
    "report_public_url":
      "http://reporting.trader.adgear.com/reports/public/628a3960-521a-11e3-8f96-0800200c9a66"
  }

Retrieve a Report [GET]

• Response 200 (application/json)
  [Report][]
• Response 403 (application/json)
• Response 404 (application/json)

Delete a Report [DELETE]

• Response 204
• Response 403 (application/json)
• Response 404 (application/json)

Report Listing [/v1/reports]

• Query parameters
  • sort (optional, string, author_id:-query.type) The sort order for listing Reports.
    A list of fields by which to sort. Fields are separated by colons (:) and are considered from left to right. Direction of sorting is ascending, unless the field name is prefixed with a minus sign (-).
    For example, to sort by decreasing id and then by increasing creation date, use sort=-id:created_at.
  • filters (optional, string, status==completed:created_at>=2016-04-12) The filter for listing Reports.
    Filters can be used to exclude records from the data you are retrieving. Filters are separated by colons (:). The syntax of a single filter is a field name, followed by a filtering operator, followed by a filter expression. For example, to only retrieve the reports that are not in the error status, use filters=status!=error. To additionally filter on records where the query type was adgear_agency_delivery, use filters=status!=error:query.type==adgear_agency_delivery.
    • Filtering operators
      

      Operator	Description
      ==	equals
      !=	does not equal
      >	greater than
      <	less than
      >=	greater or equal
      <=	less or equal
      =@	substring match
      !@	substring does not appear
      =~	regexp match
      !~	regexp does not match

      It is permissible to filter and sort on a field that does not get output. For example, to retrieve only the records that include new as a substring in their title, you can use filters=title=@new, even though the title field does not get set by the service.
      Note also that the filtering and sorting expressions should be properly URL-encoded (characters <, =, and > become %3C, %3D, and %3E, respectively), and that reserved characters ;, ,, :, and \ must be quoted (preceded by a backslash, \) to be included in an expression. For example, to select records where the title contains version:2\beta as a substring, use filters=title%3D@version\:2\\beta (the ability to quote special characters is mainly useful for regular expressions).
    • limit (optional, integer) The maximum number of reports to return. Defaults to 200. Maximum of 200 results returned. If more results are required you must do pagination using offset and limit.
    • offset (optional, integer) The starting offset of Reports to be returned, usually used in conjunction with limit, to obtain paged output. Defaults to 0.
  • search_string (optional, string)
    Free-text search term that is pattern matched against id and title fields of each report to minimize number of returned records. If any filters are provided and the search_string value is present, then returned records should satisfy both constraints.
    
    Matching modes:
    • For title field the search term will be matched anywhere in the field
    • For id field the search term will be matched from the start of the field
• Model (application/json)
  

  [{
    "id" : 1,
    "public_id" : "7c3d6110-f243-4e0b-8782-78628b41b857",
    "status" : "completed",
    "urls" : [ "http://reporting.trader.adgear.com/a70250fd-e071-425a-aae9-f2294f7d81fc.csv.gz" ],
    "secure_urls" : [ "https://reporting.trader.adgear.com/a70250fd-e071-425a-aae9-f2294f7d81fc.csv.gz" ],
    "created_at" : "2014-04-06T19:39:02.493Z",
    "author_name" : "Json Smith",
    "title" : "test title",
    "query" : {
      "type" : "adgear_agency_delivery",
      "limit" : 1,
      "offset" : 0
    },
    "report_url": "http://reporting.trader.adgear.com/reports/1",
    "report_public_url":
      "http://reporting.trader.adgear.com/reports/public/7c3d6110-f243-4e0b-8782-78628b41b857"
  }, {
    "id": 2,
    ...
  }]

• HTTP request headers
  • X-Data-Availability(Optional, string) Specifies the execution behaviour if the supplied end_date exceeds the latest date of available data for the given query.
    1. <default> Run the requested query unmodified regardless of whether all data is available.
    2. hard Do not execute the query and return HTTP 409 response code. (‘data not available’)
    3. soft Change the end_date of the executed query to match the latest date of available data. This ensures that no partial data is returned
• HTTP response headers
  • X-Data-Available (date specified in terms of milliseconds since the epoch) The high watermark time of the latest available data for the given query.

Also, for each source of supplied data for a given query an X-Data-Available-<source> is also returned. e.g. X-Data-Available-attribution, X-Data-Available-delivery

The following response HTTP headers are returned:

• X-pagination-total (integer) The total count of reports available for the given filter.
• X-pagination-limit (integer) The number of reports requested.
• X-pagination-offset (integer) The offset of the current page.
• X-pagination-prev (string) The url of the previous page.
• X-pagination-next (string) The url of the next page.

List Reports [GET]

• Response 200 (application/json)
  [Report Collection][]
• Response 403 (application/json)

Create a Report [POST]

• Request (application/json)
  [Report][]
• Response 201 (application/json)
  [Report][]
• Response 403 (application/json)

Public Report [/v1/reports/public/{uuid}]

In order to share reports, we provide a non-authenticated endpoint for retrieving minimal information on a report. The public identifier acts as an access token for a specific report.

• Parameters
  • uuid (required, uuid, c78791a7-682a-4a57-9133-07b782f3d34a) The public identifier of the Report.
• Model (application/json)
  

  {
    "public_id": "c78791a7-682a-4a57-9133-07b782f3d34a",
    "status": "completed",
    "url": [
      "http://reporting.trader.adgear.com/archive/c78791a7-682a-4a57-9133-07b782f3d34a.tsv.zip",
      "http://reporting.trader.adgear.com/archive/c78791a7-682a-4a57-9133-07b782f3d34a.csv.gz"
    ]
  }

Retrieve a Report without authentication [GET]

• Response 200 (application/json)
  [Public Report][]
• Response 404 (application/json)