--- title: "Endpoints (Trader API v1)" slug: "endpoints-trader-api-v1" updated: 2023-06-26T08:18:02Z published: 2023-06-26T08:18:02Z canonical: "help.dsp.samsungads.com/endpoints-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. # Endpoints (Trader API v1) ## Report Endpoints ### Report [/v1/reports/{id}] - Parameters - id (required, integer, `1`): The identifier of the Report. - Model (application/json) ```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" } ``` #### 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) ```actionscript [{ "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) ```actionscript { "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)