"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

GuidesAPI ReferenceChangelog

GET-ting Data from the API

Using the GET request you can query individual objects or lists of objects through the Buzz API. Buzz will automatically restrict you to objects in your Account and for which you have permission to read. In addition, only certain fields are query-able for a given object.

📘

Migration Notes from 0.5 API

  • Variables should be passed as URL-encoded parameters. The 0.5 API also supported variables in the request body, but this is no longer supported.
  • Views are no longer supported and are replaced by Reference Resources.
  • The fields parameter is no longer supported.
  • To query across accounts use all_accounts=true instead of account_id=any

Examples of GET requests

Examples of various parameters accepted for GET requests are shown below. In these examples, the [host] would be replaced with your API endpoint and the [resource] would be replaced with the specific resource you are querying.

To modify the filtering criteria for a given field to be a non-exact match, you append a modifier to the field name preceded by a double-underscore. For example, to filter field_name such that the value is greater than or equal to the number 123, you would express the URL parameter as field_name__gte=123.

Basic syntax

# Gets all objects corresponding to the [resource] in the account (no selection criteria provided)
curl -X GET "[host]/rest/v2/[resource]" -b cookies.txt

Example of GET response

When a GET request successfully executes, the response includes the count, next, and previous fields, along will the results field which includes a list of objects containing the data requested (see Common Fields in GET Responses). Example of a successful GET response:

{
	"count": 1,
	"next": null,
	"previous": null,
	"results": [{
		"id": 1,
		"sample_field_name": "sample_field_value",
		"create_date": "2020-06-22 08:18:12",
		"update_date": "2020-06-22 08:18:12",
		"active": true,
		"alternative_id": null,
		"notes": null,
		"name": null,
		"account_id": 2
	}]
}

📘

Float Values Returned as Strings

Note, when a field in a GET response includes a float value, such as a budget, it is returned as a string.

Filter by ID

#Get the object with id=1
curl -X GET "[host]/rest/v2/[resource]?id=1" -b cookies.txt

Filter by ID in path

#Get the object with id=1 (alternative format)
curl -X GET "[host]/rest/v2/[resource]/1" -b cookies.txt

Multiple values for single field (__in)

#Get objects with field values 1, 2, or 3. In example below the variable name is field_name 
curl -X GET "[host]/rest/v2/[resource]?field_name__in=1,2,3" -b cookies.txt

Exact match (default)

#Get object with exact match of field name
curl -X GET "[host]/rest/v2/[resource]?field_name=field_value" -b cookies.txt

Search in fields

#Get object that contains a word anywhere in the field (case insensitive).
curl -X GET "[host]/rest/v2/[resource]?field_name__contains=field_value" -b cookies.txt

#Search term must be at the start of the field (case insensitive)
curl -X GET "[host]/rest/v2/[resource]?field_name__startswith=field_value" -b cookies.txt

#Search term must be at the end of the field (case insensitive)
curl -X GET "[host]/rest/v2/[resource]?field_name__endsswith=field_value" -b cookies.txt

Not (__not)

#Get any object that does not match a word in the field
curl -X GET "[host]/rest/v2/[resource]?field_name__not=field_value" -b cookies.txt 

#Get any object that does not contain a word within the field
curl -X GET "[host]/rest/v2/[resource]?field_name__not_contains=field_value" -b cookies.txt 

#Get any object that does not match a list of values
curl -X GET "[host]/rest/v2/[resource]?field_name__not_in=1,2,3" -b cookies.txt

Comparators

# Get any object with a comparator. See examples below.

#Use __gt for greater than 
curl -X GET "[host]/rest/v2/[resource]?field_name__gt=field_value" -b cookies.txt 

#Use __lt for less than 
curl -X GET "[host]/rest/v2/[resource]?field_name__lt=field_value" -b cookies.txt

#Use __gte for greater than or equals 
curl -X GET "[host]/rest/v2/[resource]?field_name__gte=field_value" -b cookies.txt

#Use __lte for less than or equals
curl -X GET "[host]/rest/v2/[resource]?field_name__lte=field_value" -b cookies.txt

#Use __range for between two values (dates, numeric, strings) 
curl -X GET "[host]/rest/v2/[resource]?field_name__range=(start, end)" -b cookies.txt

Blank or NULL values (__isempty)

# Get any object where the field is NULL
curl -X GET "[host]/rest/v2/[resource]?field_name__isempty=true" -b cookies.txt 

# Get any object where the field is not NULL
curl -X GET "[host]/rest/v2/[resource]?field_name__isempty=false" -b cookies.txt

Multiple parameters

# Get an object with the word “advertiser” in its name, that is also currently active.
curl -X GET "[host]/rest/v2/[resource]?field_name__contains=advertiser&active=1" -b cookies.txt

Date comparisons (__range)
See: Date Filtering.

# Get an object that was created since yesterday. Date fields can be filtered using a number of "magic" strings.

curl -X GET "[host]/rest/v2/[resource]?create_date__range=yesterday" -b cookies.txt

Querying a specific account other than the one in which you are authenticated (Multi-Account must be enabled):

# If both your account and user are enabled for multi-account access you may query across accounts by including the account_id field in the query
curl -X GET "[host]/rest/v2/[resource]?field_name=foo&account_id=23" -b cookies.txt

Querying across all accounts (Multi-Account must be enabled):

# If both your account and user are enabled for multi-account access you may query across accounts by including all_accounts=true in the query
curl -X GET "[host]/rest/v2/[resource]?field_name=foo&all_accounts=true" -b cookies.txt

Special Query Parameters for GETs

GET requests support four special query parameters that allow you to paginate and sort the results. These parameters are always optional.

GET ParameterUsageDefault
pagePage of results to return. Generally accepts an integer, but can also accept last for the final page of results.1
page_sizeNumber of results to return in a single request. Note, the maximum value is 1000.50
orderThe fields to sort by. Only searchable fields can be used to sort.

Accepts multiple fields in a comma-separated list order=field1,field2

To reverse the sort order add - sign before the field like order=-field1		The first field, typically the unique ID of the object

Exporting GET Results

We do not currently support exporting GET results as csv, Excel, etc but expect to in the near future.

Specifying a Timezone

By default all API requests are returned in the Account-level timezone, generally America/New_York. API users can force all date fields to be in another timezone for convenience by adding the X-Timezone header to the API request with a valid timezone.

#Request all dates in UTC
curl -X GET "[host]/rest/v2/[resource]?field_name=foo" -b cookies.txt 
	-H "X-Timezone: UTC"

#Request all dates in Los Angeles
curl -X GET "[host]/rest/v2/[resource]?field_name=foo" -b cookies.txt 
	-H "X-Timezone: America/Los_Angeles"

Updated almost 3 years ago

What’s Next