--- title: "Overview (Trader API v1)" slug: "overview-trader-api-v1" updated: 2023-06-26T07:29:08Z published: 2023-06-26T07:29:10Z canonical: "help.dsp.samsungads.com/overview-trader-api-v1" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.dsp.samsungads.com/llms.txt > Use this file to discover all available pages before exploring further. # Overview (Trader API v1) ## AdGear reporting service API documentation The reporting service is used to query our analytics database through a REST interface. Since the execution time and result set size of a given query are not known in advance and may be large, the interface we provide is asynchronous. The core model is a query. The query structure defines the computation that will be run on the analytics engine. The parameters that are required for all queries are a type (representing the fact table), a date range (limiting the rows considered), a list of dimensions that are required to pivot and a list of metrics to aggregate around the dimensions. Here’s an example of a valid query: ```actionscript { "type": "trader_delivery", "start_date": "2016-04-01T00:00:00", "end_date": "2016-04-07T23:59:59", "time_zone": "America/Montreal", "dimensions": ["month", "campaign_id", "flight_id"], "metrics": ["impressions", "impressions_dropped", "clicks", "clicks_dropped", "ctr"], "filter": "advertiser_id = 52", "metrics_filter": "impressions > 100", "order_fields": ["month", "-impressions"], "limit": 10 } ``` Note that specifying both a start and an end date is mandatory, but the time zone is optional, and will default to UTC (which can also be specified explicitly using time zone “Etc/UTC”). Valid time zone names include “America/Los_Angeles”, “America/Toronto”, “America/Montreal”, “America/New_York”, and “Europe/London”. In a query, the `filter` field takes the shape of a SQL predicate expression (the kind of subexpression one can put in a `WHERE` clause): a more complex example than the `advertiser_id = 52` filter above could be `advertiser_id = 52 AND advertiser_name = 'Acme'`. Likewise, `metrics_filter` is a SQL boolean expression, to be used as an aggregate filter (`HAVING` clause), for example `impressions > 100 AND impressions < 800`. The next most important model is the Report. A report is mostly metadata that surrounds a query. The workflow of a query is the following: - User asks for a report to be built; - the reporting service acknowledges the query and gives the user information needed to query its status ; - the reporting service executes the query in background: - on success, the results get saved and we notify the user with URLs; - on failure, we notify the user of the failure. Here’s an example of a report: ```actionscript { "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", "output_formats": [ {"format" : "tsv", "compression" : "zip"}, {"format" : "csv", "compression" : "gzip"}, {"format" : "xlsx", "compression" : "none"} ] } ``` On report completion (successful or not), e-mail addresses mentioned receive a message giving a short summary of the report’s status and instructions to download the actual report (essentially, the value of the report_public_url field). Callbacks URLs receive, as a POST request body, a JSON description of the report, in the same format as the example above. Error codes are as follows: - 1 - UNEXPECTED ERROR - 2 - QUERY EXECUTION TIMEOUT EXCEEDED ## Authentication Authentication credentials must be provided using an ‘Authorization’ HTTP header with a value specified as follows: ‘Bearer :’