apiary.apib

FORMAT: 1A
HOST: https://platform.adstage.io/api

# AdStage API Concepts
The AdStage API allows you to pull normalized data of any granularity from many ad networks and marketing analytics tools using a unified interface.
Data sources include Google Ads, Microsoft Ads, Facebook, LinkedIn, Twitter, Instagram, Gemini, Google Analytics, and more.

AdStage's JSON APIs broadly allow developers to:
* Access data about their AdStage users, organizations, and advertising entities
* Upload custom data for use within the AdStage platform
* Pull customizable reports on advertising data in a single, normalized format

AdStage provides two API versions: V1, which is a fully stable and fully released API version, and V2, which is a fully stable version with release in progress.
Though V1 may occasionally be an appropriate choice to access certain legacy features not yet available in V2, in most cases V2 should be preferred due to its generally expanded feature set, shorter maintenance cycles, and faster performance.
When choosing a particular version, check the documentation in both versions before determining the best option.

Across endpoints and versions, AdStage APIs often refer to several key concepts, documented in this section.
The next sections group version-specific documentation for the API endpoints and common workflows.

## Date Ranges

The AdStage endpoints use date range strings to represent time periods and implement a unified date range format throughout the platform.
Date range strings can be written in two possible styles: either an absolute range such as `"2016-12-25..2016-12-31"`, or a relative range, such as `"last 30 days"` or `"this month"`.

### Explicit Date Ranges
Absolute date ranges must be formatted as `yyyy-mm-dd..yyyy-mm-dd` and refer to data for all calendar days between the two dates provided (inclusive).

Relative date ranges must be formatted according to the following chart, where `X` is an integer, and `TIME_UNIT` is one of `day`, `week`, `month`, `quarter`, or `year`:

| Relative Date String | Time Period Returned | Example (if today is `2019-06-15` in UTC) |
| -------------------- | -------------------- | ------- |
| `today` | A 24 hour timeslice starting at the most recent midnight | `"today"` == `2019-06-15T00:00:00Z - 2019-06-15T23:59:59Z` |
| `yesterday` | A 24 hour timeslice ending directly before the most recent midnight | `"yesterday"` == `2019-06-14T00:00:00Z - 2019-06-14T23:59:59Z` |
| `{{TIME_UNIT}} to date` | A timeslice from the beginning of the most recent `TIME_UNIT` ending at the most recent midnight | `"month to date"` == `2019-06-01T00:00:00Z - 2019-06-14T23:59:59Z` |
| `{{X}} {{TIME_UNITS}} to date` | A timeslice from the beginning of the `X`th most recent `TIME_UNIT` ending at the most recent midnight | `"2 months to date"` == `2019-05-01T00:00:00Z - 2019-06-14T23:59:59Z` |
| `{{TIME_UNIT}} to now` | A timeslice from the beginning of the most recent `TIME_UNIT` ending at the upcoming midnight | `"quarter to now"` == `2019-04-01T00:00:00Z - 2019-06-15T23:59:59Z` |
| `{{X}} {{TIME_UNITS}} to now` | A timeslice from the beginning of the `X`th most recent `TIME_UNIT` ending at the upcoming midnight | `"2 quarters to now"` == `2019-01-01T00:00:00Z - 2019-06-15T23:59:59Z` |
| `this {{TIME_UNIT}}` | A timeslice of 1 `TIME_UNIT` starting at the beginning of the most recent `TIME_UNIT` and ending directly before the start of the next `TIME UNIT` | `"this month"` == `2019-06-01T00:00:00Z - 2019-06-30T23:59:59Z` |
| `this {{X}} {{TIME_UNITS}}` | A timeslice of `X` `TIME_UNITS` terminating at the end of the current `TIME_UNIT` | `"this 2 months"` == `2019-05-01T00:00:00Z - 2019-06-30T23:59:59Z` |
| `last {{TIME_UNIT}}` | A timeslice of 1 `TIME_UNIT` starting at the beginning of the most recent `TIME_UNIT` and ending directly before the start of the next `TIME_UNIT` | `"last month"` == `2019-05-01T00:00:00Z - 2019-05-31T23:59:59Z` |
| `last {{X}} {{TIME_UNITS}}` | A timeslice of `X` `TIME_UNITS` terminating directly before the start of the most recent `TIME_UNIT` | `"last 2 months"` == `2019-04-01T00:00:00Z - 2019-05-31T23:59:59Z` |

Any date range string, either absolute or relative, may append a modifying prefix to shift the date range:

| Relative Date String | Time Period Returned | Example (if today is `2019-06-15` in UTC) |
| -------------------- | -------------------- | ------- |
| `previous_period {{ABSOLUTE_DATE_RANGE}}` | A timeslice the size of `ABSOLUTE_DATE_RANGE`, ending directly before the start of `ABSOLUTE_DATE_RANGE` | `"previous_period 2019-06-10..2019-06-14"` == `2019-06-05T00:00:00Z - 2019-06-09T23:59:59Z` |
| `previous_period {{RELATIVE_DATE_RANGE}}` | A timeslice the size of `RELATIVE_DATE_RANGE`, ending directly before the start of `RELATIVE_DATE_RANGE`. The size is based off of the `TIME_UNIT` of the `RELATIVE_DATE_RANGE`, so the previous period may have a different number of days if the `TIME_UNIT` varies in number of days. | `"previous_period this month"` == `2019-05-01T00:00:00Z - 2019-05-31T23:59:59Z` (note this returns a 31 day slice, while `this month` returns a 30 day slice) |
| `previous_{{TIME_UNIT}} {{ABSOLUTE_DATE_RANGE}}` | A timeslice the size of `ABSOLUTE_DATE_RANGE` but shifted back one `TIME_UNIT`. The end of `ABSOLUTE_DATE_RANGE` can be truncated if the `TIME_UNIT` varies in number of days.  | `"previous_month 2019-05-11..2019-05-31"` == `2019-04-11T00:00:00Z - 2019-04-30T23:59:59Z` (note this returns a 20 day timeslice, while the original date range covered 21 days) |
| `previous_{{TIME_UNIT}} {{DATE_RANGE}}` | A timeslice the size of `DATE_RANGE` but shifted back one `TIME_UNIT`. The end of `DATE_RANGE` can be truncated if the `TIME_UNIT` varies in number of days.  | `"previous_month 2019-05-11..2019-05-31"` == `2019-04-11T00:00:00Z - 2019-04-30T23:59:59Z` (note this returns a 20 day timeslice, while the original date range covered 21 days) |

### Inferred Single Day Ranges
When giving the API a single date, it will interpret the value as a date range spanning that day only:

| Single Date String | Time Period Returned | Example (if today is `2019-06-15` in UTC) |
| -------------------- | -------------------- | ------- |
| `{{ABSOLUTE_DATE}}` | A 24 hour timeslice covering the given date | `"2018-02-12"` == `2018-02-12T00:00:00Z - 2018-02-12T23:59:59Z` |
| `today` | A 24 hour timeslice starting at the most recent midnight | `"today"` == `2019-06-15T00:00:00Z - 2019-06-15T23:59:59Z` |
| `yesterday` | A 24 hour timeslice ending directly before the most recent midnight | `"yesterday"` == `2019-06-14T00:00:00Z - 2019-06-14T23:59:59Z` |
| `{{X}} {{TIME_UNITS}} ago` | A 24 hour timeslice covering the full day `X` `TIME_UNIT`s before the current date | `"2 weeks ago"` == `2019-06-01T00:00:00Z - 2019-06-01T23:59:59Z` |

## Entity IDs

AdStage has two styles of IDs that refer to a specific advertising entity (for example, a specific campaign or a specific keyword).
Though other forms of IDs may be found in some response endpoints, the newest version - the `entity_id` - should be strongly preferred, as AdStage may drop maintenance of other ID types in the future.

Often, it can be convenient to generate these ids manually without looking up the entity in the AdStage API.
To generate the entity id by hand, use the following string template:

`"/network/{network}/{entity_level}/{remote_id}"`, where:

+ The `{network}` variable must be be one of:
    + `adwords`
    + `amazon`
    + `bing_ads`
    + `facebook`
    + `gemini` (not available in cross-network reporting; see Build Report V1)
    + `google_analytics` (not available in cross-network reporting; see Build Report V1)
    + `linkedin`
    + `pinterest`
    + `quora`
    + `spotify`
    + `twitter`
    + `adstage` (with entities managed on the AdStage platform: `account_group`, `user`, `organization` and `folder`)
+ The `{entity_level}` variable must be one of:
    + `account`
    + `campaign`
    + `ad_group`
    + `ad`
    + `keyword` (including all Microsoft Ads keywords)
    + `criterion` (including all Google Ads keywords)
+ The `{remote_id}` variable must be the entity's ID on the advertising network. This can be obtained directly from the advertising network - often the entity's URL contains the `remote_id` in the relevant network's UI. Alternatively, the AdStage reporting endpoints can query `remote_id`s when a report includes the following meta fields:
    + `remote_account_id`
    + `remote_campaign_id`
    + `remote_ad_group_id`
    + `remote_ad_id`
    + `remote_keyword_id` (includes results for `criterion` ids)

## HAL JSON Resources

The AdStage API models the data it returns as discrete resources, each of which can have rich relationships to other resources.
Relationships among API resources is modeled in JSON responses with the [Hypertext Application Language (HAL) standard](https://en.wikipedia.org/wiki/Hypertext_Application_Language).
For example, an endpoint returning comprehensive data about a user may also return links to other related resources, such as the user's organization, in the JSON response.
Though a full overview of HAL is beyond the scope of this documentation, this section explains the basic principles needed to successfully interact with the rich data in most AdStage HAL responses.
HAL attempts to make JSON navigable by organizing JSON content and providing links to related content similar to how HTML organizes web content.
Just as a web page allows human users to view content and follow links to related pages, HAL allows automated systems to access JSON content and discover links to related JSON endpoints.

AdStage's HAL JSON responses are divided into four distinct sections: the main response (inside the top level JSON object), `_embedded`, `_links`, and `_forms`.

The main response contains information about the requested resource.
The `_embedded` object contains resources related to the requested resource.
The `_links` object contains URLs that define API requests for related resources or URLs for next and previous pages of the current resource.
Note that both the main request and also any embedded resources may include links specific to that resource.
The `_forms` object can optionally be provided with a link to describe various options that can be used to change or enhance the request, often with recommended submission values.

## Embedded Resources

When issuing a request to a HAL endpoint, the requested resource will typically appear inside the top-level JSON response body.
However, the response body may also contain `_embedded` objects containing information about resources related to the parent resource.
For example, when requesting information about a user in example below, the main JSON body returns data about that user, and the `_embedded` key returns information about the user's organization.

Note that any particular resource returned in the `_embedded` object may have additional HAL resources, links, and forms of its own.

**Modified HAL response from a request to a user data endpoint**

```
{
    // The main response contains data about the user resource,
    // which was the item requested from the endpoint
    "avatar_url": "https://www.gravatar.com/avatar/123456",
    "created_at": 1522185933,
    "customer_status": "trialing",
    "default_organization_role": "OWNER",
    "email": "polarbear@adstage.io",
    "fetch_id": 1,
    "id": "/api/users/1",
    ...,

    // The embedded section of the response returns data about the user's organization
    // because API consumers frequently wish to use data from both resources at once
    "_embedded": {
        "adstage:organization": {
            "active_accounts_count": 9,
            "is_active_customer": true,
            "id": "/api/organizations/1",
            "user_count": 1,
            ...,

            // The embedded resource has HAL resources of its own,
            // such as links to additional resources related to the *organization*.
            "_links": {
                "profile": [
                    {
                        "name": "organization",
                        "href": "http://platform.adstage.io/api/docs/profile/organization"
                    }
                ],
                ...
            },
            ...
        },
        ...
    },
    ...
}
```

## Links

HAL resources may contain links to other related resources in the `_links` object.
Applications can follow the URLs in links to access these resources.

_Note that some links in the API responses may contain URLs for endpoints not documented here.
These are not maintained as stable for external users and are not supported.
Please check whether a link's endpoint is documented here before using it in your application.
Most supported HAL links for API customers are pagination related._

**Modified HAL response from a request to a user data endpoint**

```
{
    // The main response contains data about the user resource,
    // which was the item requested from the endpoint
    "avatar_url": "https://www.gravatar.com/avatar/123456",
    "created_at": 1522185933,
    "customer_status": "trialing",
    "default_organization_role": "OWNER",
    "email": "polarbear@adstage.io",
    "fetch_id": 1,
    "id": "/api/users/1",
    ...,

    // The _links section of the response returns links related to the given user,
    // such as a full description of the user's organization
    // and lists of the user's accounts
    "_links": {
        "adstage:organization": {
            "href": "http://platform.adstage.io/api/organizations/1"
        }

        // Occasionally links may include templates for URL parameters that can refine the request
        "adstage:list": [
            {
                "templated": true,
                "name": "adwords_accounts",
                "href": "http://platform.adstage.io/api/users/1/list_network_accounts/adwords{?limit,offset,sort_by,order,term}"
            },
            {
                "templated": true,
                "name": "bing_ads_accounts",
                "href": "http://platform.adstage.io/api/users/1/list_network_accounts/bing_ads{?limit,offset,sort_by,order,term}"
            },
            ...
        ],
        ...
    },
    ...
}
```

## Forms

Though forms are not officially part of the HAL standard, AdStage uses a common forms implementation in some responses.
In these responses, HAL links may also provide a related form that describes options for submitting richer data to an endpoint.
In particular, forms allow HAL to describe how to complete a non-GET request requiring complex or lengthy parameters in a JSON body.
In a few cases, forms describe a menu of allowable options for such a request and then expect the client application to determine which values to actually send from those options.
However, AdStage typically uses forms merely as more descriptive links by designating suggested values for all of the request's JSON parameters.

_Note that some forms in the API responses may contain URLs for endpoints not documented here.
These are not maintained as stable for external users and are not supported.
Check whether a form's endpoint is documented here before using it in your application.
Most supported HAL forms for API customers are pagination related._

**Modified HAL response from a reporting request**

```
{
    // The main report resource
    "summary": { ... },
    "type": "rows",
    "time": {
        "end": "2019-06-26T23:59:59Z",
        "start": "2019-06-26T00:00:00Z"
    },
    ...,

    // A link gives "fallback" information about the next page resource,
    // but the form should be used instead since the link shows "form": true
    "_links": {
        "results": [],
        "next_page": {
            "href": "https://platform.adstage.io/api/organizations/1/report",
            "method": "POST",
            "form": true
        }
    }

    // The form includes information needed to make a request to the URL
    // using a rich JSON body instead of just URL parameters
    "_forms": {
        "next_page": {
            "href": "https://platform.adstage.io/api/organizations/1/report",

            // Note that the the HTTP method for a form always uses a JSON body
            "method": "POST",

            // Each field shows a JSON key, a JSON Schema V4 type, and a suggested value
            "fields": {

                // For example, this item asks users to include `"date_range": "yesterday"`
                // in the JSON body for the request
                "date_range": {
                    "type": "string",
                    "value": "yesterday"
                },
                "fields": {
                    "type": "array",
                    "value": [
                        "spend"
                    ]
                },
                ...,
                "page_token": {
                    "type": "string",
                    "value": "g3QAAAADZAAFbGltaXRhGWQABm9mZnNldGEyZAABdG0AAAAGb2Zmc2V0"
                }
            }
        }
        ...
    }
    ...
}
```

## Pagination

Most AdStage API endpoints that return lists or reports have support for pagination via HAL JSON links or forms.
You can specify the number of items or rows to return with a `limit` parameter, and you can page through results by adding an `offset` parameter to subsequent requests.
For your convenience, the responses from these endpoints also include links to the next and previous pages; some endpoints may also provide links to first and last pages.

**Limit/offset pagination example:**
```
{
    // The data for this page
    "_embedded": { ... },

    // Links to related pages
    "_links": {
        "next": {
            "href": "https://platform.adstage.io/api/organizations/1/build_report?limit=1000&offset=3000&..."
        },
        "prev": {
            "href": "https://platform.adstage.io/api/organizations/1/build_report?limit=1000&offset=1000&..."
        },
    }
}
```

Some newer endpoints may return a page token in the response link or form.
When a providing the page token as a parameter in a subsequent HTTP request, AdStage will locate the proper page of data with the page token without the need to manually manage limit and offsets.
AdStage generated tokens will always encode the proper limit and offset for the designated page, and may attempt to encode a reference to a cached page for faster performance.
If a request provides both a limit and/or offset as well as a page token, AdStage will attempt to locate the page based on the page token.

**Token pagination example:**
```
{
    // The data for this page_page
    "_embedded": { ... },

    // Links to related pages
    "_links": {
        "next_page": {
            "href": "https://platform.adstage.io/api/organizations/1/build_report?page_token=g3QAAAADZAAFbGltaXRhGWQABm9mZnNldGEyZAABdG0AAAAGb2Zmc2V0&..."
        },
        "prev_page": {
            "href": "https://platform.adstage.io/api/organizations/1/build_report?page_token=g3QAAAADZAAFbGltaXRhGWQABm9mZnNldGEAZAABdG0AAAAGb2Zmc2V0&..."
        }
    }
}
```

## Authentication

AdStage uses HTTP header bearer tokens for API authentication.
Contact the AdStage Customer Success team at `support@adstage.io` or your organization's account manager to receive an authentication token.

### OAuth 2 Applications
If would like to create a application for multiple AdStage users, the AdStage API can serve as an OAuth 2 provider.
However, there is currently no self-service method to register new OAuth2 applications.
Contact the AdStage Customer Success team at `support@adstage.io` to have a `client_id` and `client_secret` provisioned for your application.

## Status

Keep up to date with any problems the AdStage API might be experiencing on our [status page](http://status.adstage.io/).

# Group AdStage API V1

This version of the AdStage API can be considered stable and fully released.

## Discovering Basic Organization Data [/]

The following endpoints allow developers to discover key resources belonging to the developer's organization and API user.

### Current User [GET /me{?type}]

+ Request
    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + type (string, optional) - When `lightweight`, provides a substantially more compact response by omitting several HAL resources; recommended for most use cases


+ Response 200 (application/json)

            {
                "first_name": "Clark",
                "last_name": "Gates-George",
                "email": "clark@adstage.io",
                "created_at": 1351707901,
                "id": "/api/users/1",
                "fetch_id": 40,
                "has_linked": true,
                "account_status": {
                    "adwords": "unimportable",
                    "bing_ads": "unimportable",
                    "facebook": "currently_importing",
                    "linkedin": "permanent_authentication_error",
                    "twitter": "currently_importing"
                },
                "visible_account_status": {
                    "adwords": "unimportable",
                    "bing_ads": "unimportable",
                    "facebook": "currently_importing",
                    "linkedin": "currently_importing",
                    "twitter": "currently_importing"
                },
                "_embedded": {
                    "adstage:organizations": [
                        {
                            "id": "/api/organizations/1",
                            "fetch_id": 40,
                            "active_accounts_count": 45,
                            "is_active_customer": true,
                            "additional_accounts_purchased": 23,
                            "advertiser_type": "Agency / Consultant",
                            "advertising_objective": "Unknown",
                            "billable_accounts_count": 43,
                            "billing_contact_email": "clark@adstage.io",
                            "is_billing_error": false,
                            "blurb": "Connect ad accounts to the AdStage analytics dashboard and compare performance.  View current key performance metrics (CPA, CPM, CTR) at a glance. Measure your advertising ROS with customizable graphs that allow you to easily gauge performance across multiple networks for any historical period. AdStage identifies your top-performing ads and keywords, which helps you determine what wording resonates well with your audience. Use that ad messaging in your sales pitch, blog posts, or website copy. ",
                            "company_name": "AdStage",
                            "customer_status": "paying",
                            "is_former_customer": false
                        }
                    ]
                }
            }

### Organization [GET /organizations/{org_id}]

+ Parameters

    + org_id: 1 (number)
        The fetch_id for the organization to be reported.

+ Request
    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

+ Response 200 (application/json)

    + Attributes

        + id: /api/organizations/1 (string)
            The path to the organization in the AdStage API.

        + fetch_id: 40 (number)
            The fetch id for the organization being reported.

    + Body

            {
                "active_accounts_count": 45,
                "is_active_customer": true,
                "additional_accounts_purchased": 23,
                "advertiser_type": "Agency / Consultant",
                "advertising_objective": "Unknown",
                "billable_accounts_count": 43,
                "billing_contact_email": "clark@adstage.io",
                "is_billing_error": false,
                "blurb": "Connect ad accounts to the AdStage analytics dashboard and compare performance.",
                "company_name": "AdStage",
                "company_url": "http://www.adstage.io",
                "cumulative_monthly_spend": 12654,
                "customer_status": "paying",
                "fetch_id": 40
            }

### Accounts [GET /users/{user_id}/list_network_accounts/all]

+ Parameters

    + `user_id`: 40 (number)
        The id for the user that owns the accounts to be listed.

+ Request

    + Headers

            Accept: application/json
            Authorization: Bearer de4dxxxxb33f

+ Response 200

    A list of accounts.

    + Attributes
        + `_links` (object)
            + next (object)
                + href (string) - A URL to get the next page of accounts

                    `"https://platform.adstage.io/api/users/40/list_network_accounts/all?limit=10&offset=20"`

            + prev (object)
                + href (string) - A URL to get the previous page of accounts

                    `"https://platform.adstage.io/api/users/40/list_network_accounts/all?limit=10&offset=0"`

        + `_embedded` (object)
            + item (array)
                + (object)
                    + remote_id: "12345" (string) - the identifier assigned to this account by the ad network
                    + network: "adwords" (string) - the ad network for the given account
                    + name: "AdWords Account #1" (string) - the human readable name for the account
                    + is_visible: true (boolean) - whether or not this account is visible

    + Body

            {
                "_embedded": {
                    "item": [
                        {
                            "remote_id": "12345",
                            "network": "adwords",
                            "network_name": "AdWords",
                            "name": "AdWords Account #1",
                            "is_visible": true,
                            "currency_code": "USD",
                            "status": "ACTIVE",
                            "_embedded": {},
                            "_forms": {
                                "adstage:unlink": {
                                    "href": "https://platform.adstage.io/api/organizations/40/unlink_network_account",
                                    "method": "PUT",
                                    "fields": {
                                        "network": {
                                            "type": "hidden",
                                            "value": "adwords"
                                        },
                                        "network_account_id": {
                                            "type": "hidden",
                                            "value": "12345"
                                        }
                                    }
                                }
                            },
                            "_links": {
                                "self": {
                                    "href": "https://platform.adstage.io/api/network/adwords/accounts/12345",
                                    "title": "AdWords Account #1"
                                }
                            }
                        }
                    ]
                },
                "_links": {
                    "next": {
                        "href": "https://platform.adstage.io/api/users/40/list_network_accounts/all?limit=1&offset=1&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=name&order=asc"
                    }
                },
                "counts": {
                    "overall": 5,
                    "page": 1
                },
                "current_page": 1,
                "id": "https://platform.adstage.io/api/users/40/list_network_accounts/all?limit=1&offset=0&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=name&order=asc",
                "list_of": "item",
                "page_options": {
                    "limit": 1,
                    "offset": 0
                },
                "page_size": 1,
                "page_total": 1,
                "total": 5,
                "total_pages": 5
            }

### Account Groups [GET /users/{user_id}/account_groups]

+ Parameters

    + user_id: 40 (number)
        The id for the user that owns the account groups to be listed.

+ Request

    + Headers

            Accept: application/json
            Authorization: Bearer de4dxxxxb33f

+ Response 200

    A list of account groups.

    + Attributes
        + _links (object)
            + next (object)
                + href (string) - A URL to get next page of account groups

                    `"https://platform.adstage.io/api/users/40/account_groups?limit=10&offset=20&networks=all"`

            + prev (object)
                + href (string) - A URL to get previous page of account groups

                    `"https://platform.adstage.io/api/users/40/account_groups?limit=10&offset=0&networks=all"`

        + _embedded (object)
            + item (array)
                + (object)
                    + id: 40 (number) - the identifier assigned to this account group
                    + name: "Client #1" (string) - the full human readable name for the metric
                    + is_visible: true (boolean) - whether all the accounts are visible in this group
                    + account_count: 5 (number) - total number of accounts in the group
                    + _forms (object) - list of actions available on the account group

    + Body

            {
                "_embedded": {
                    "item": [
                        {
                            "account_count": 1,
                            "id": 988,
                            "is_visible": false,
                            "name": "Client 3 Marketing",
                            "_embedded": {},
                            "_forms": {
                                "adstage:add": {
                                    "fields": {
                                        "network": "string",
                                        "network_account_id": "integer"
                                    },
                                    "href": "https://platform.adstage.io/api/users/40/account_groups/988/add",
                                    "method": "POST",
                                    "name": "account_group"
                                }
                            },
                            "_links": {
                                "adstage:add": {
                                    "form": true,
                                    "href": "https://platform.adstage.io/api/users/40/account_groups/988/add",
                                    "method": "POST",
                                    "name": "account_group"
                                },
                                "adstage:list": [
                                    {
                                        "href": "https://platform.adstage.io/api/users/40/account_groups/988/list_accounts{?limit,offset}",
                                        "name": "network_accounts",
                                        "templated": true
                                    }
                                ],
                                "self": {
                                    "href": "/api/users/40/account_groups/988"
                                }
                            }
                        }
                    ]
                },
                "_links": {
                    "next": {
                        "href": "https://platform.adstage.io/api/users/40/account_groups?limit=1&offset=1&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=clicks&order=desc"
                    }
                },
                "counts": {
                    "overall": 5,
                    "page": 1
                },
                "current_page": 1,
                "id": "https://platform.adstage.io/api/users/40/account_groups?limit=1&offset=0&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=clicks&order=desc",
                "list_of": "item",
                "page_options": {
                    "limit": 1,
                    "offset": 0
                },
                "page_size": 1,
                "page_total": 1,
                "total": 5,
                "total_pages": 5
            }

### Folders [GET /users/{user_id}/list_folders]

+ Parameters

    + user_id: 40 (number)
        The id for the user that owns the folders to be listed.

+ Request

    + Headers

            Accept: application/json
            Authorization: Bearer de4dxxxxb33f

+ Response 200

    A list of folders.

    + Attributes
        + _links (object)
            + next (object)
                + href (string) - A URL to get next page of folders

                    `"https://platform.adstage.io/api/users/40/list_folders?limit=10&offset=20&networks=all"`

            + prev (object)
                + href (string) - A URL to get previous page of folders

                    `"https://platform.adstage.io/api/users/40/list_folders?limit=10&offset=0&networks=all"`

        + _embedded (object)
            + item (array) - list of folders
                + (object)
                    + fetch_id: 40 (string) - the identifier assigned to this folder
                    + id: "/api/folders/40" (string) - a uri identifier for the folder
                    + name: "Folder #1" (string) - name of the folder
                    + network_counts (object) - count of campaigns in folder by network
                    + _forms (object) - list of actions available on the folder
                    + _links (object) - list of actions and related entities to the folder
                        + `adstage:network_campaign` - HAL links to adstage campaigns

    + Body

            {
                "_embedded": {
                    "item": [
                        {
                            "daily_budget_value": 0.0,
                            "fetch_id": "168",
                            "id": "/api/folders/168",
                            "lifetime_budget_value": 0.0,
                            "monthly_budget_value": 0.0,
                            "name": "040414 Updated",
                            "network_counts": {
                                "bing_ads": 1,
                                "totals": 1
                            },
                            "_forms": {
                                "adstage:link": {
                                    "fields": {
                                        "folder_id": {
                                            "title": "Choose a folder",
                                            "type": "adstage:folder",
                                            "validators": [
                                                "required"
                                            ],
                                            "value": "/api/folders/168"
                                        },
                                        "network_campaign_ids": {
                                            "title": "Choose one or more campaigns",
                                            "type": "adstage:folder",
                                            "validators": [
                                                "required"
                                            ],
                                            "value": []
                                        }
                                    },
                                    "href": "https://platform.adstage.io/api/folders/168/add",
                                    "method": "POST",
                                    "title": "Link Campaigns to Folder"
                                }
                            },
                            "_links": {
                                "adstage:network_campaign": [
                                    {
                                        "data-fetch_id": 6745,
                                        "data-id": "/api/network/bing_ads/campaigns/6745",
                                        "data-navgroup": "search",
                                        "data-network": "bing_ads",
                                        "data-network_name": "Bing",
                                        "href": "https://platform.adstage.io/api/network/bing_ads/accounts/506/campaigns/6745",
                                        "name": "/api/network/bing_ads/campaigns/6745",
                                        "network_account_id": "/api/network/bing_ads/accounts/506",
                                        "network_account_name": "AdStage, Inc.",
                                        "title": "AdStage: 040414"
                                    }
                                ],
                                "self": {
                                    "data-fetch_id": "168",
                                    "href": "https://platform.adstage.io/api/folders/168",
                                    "name": "168",
                                    "title": "040414 Updated"
                                }
                            }
                        }
                    ]
                },
                "_links": {
                    "next": {
                        "href": "https://platform.adstage.io/api/users/40/list_folders?limit=1&offset=1&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=clicks&order=desc"
                    },
                    "self": {
                        "href": "https://platform.adstage.io/api/users/40/list_folders?limit=1&access_token=57a082a0de5d9eba2d6580a3b1a7ba1876c23d0a46177f327a4289a3b272b670"
                    }
                },
                "counts": {},
                "current_page": 1,
                "id": "https://platform.adstage.io/api/users/40/list_folders?limit=1&offset=0&networks=adwords,bing_ads,facebook,linkedin,twitter&sort_by=clicks&order=desc",
                "list_of": "item",
                "page_options": {
                    "limit": 1,
                    "offset": 0
                },
                "page_size": 1,
                "page_total": 1,
                "total": 2309,
                "total_pages": 2309
            }

### Import Status [GET /users/{user_id}/sync_information]

+ Parameters

    + `user_id`: 40 (number)
        The id for the user that owns the accounts to be check the sync status.

+ Request
    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

+ Response 200 (application/json)

    A list containing import status information for each linked account.

    + Attributes
        + accounts (array)
            + (object)
                + name: "Account #1" (string) - the name of the account
                + network: "adwords" (string) - the network of the account
                + `import_status` (object) - details about the import status of the account
                    + code: "good" (string)
                        status code for the account import
                        * `good`: the most recent import has completed
                        * `currently_importing`: an import is currently running
                        * `permanent_authentication_error`: the account needs to be relinked due to an expired token or other authentication issue
                    + `is_importing`: false (boolean) - whether or not an import is currently running for the account
                    + `last_import_started`: "2018-01-01T08:30:00Z" (string) - start timestamp of the most recent import
                    + `last_import_finished`: "2018-01-01T11:11:00Z" (string)
                        if the most recent import has completed, this timestamp represents the 
                        end timestamp of the most recent import; if an import is currently
                        running, this timestamp represents the end timestamp of the previous
                        completed import

    + Body

            {
                "accounts": [
                    {
                        "name": "Account #1",
                        "network": "adwords",
                        "import_status": {
                            "code": "good",
                            "is_importing": false,
                            "last_import_started": "2018-01-01T08:30:00Z",
                            "last_import_finished": "2018-01-01T11:11:00Z",
                            "last_import_failed": null,
                            "importable": true
                        }
                    },
                    {
                        "name": "Account #2",
                        "network": "facebook",
                        "import_status": {
                            "code": "currently_importing",
                            "is_importing": true,
                            "last_import_started": "2018-01-01T12:00:00Z",
                            "last_import_finished": "2018-01-01T11:45:00Z",
                            "last_import_failed": null,
                            "importable": true
                        }
                    },
                    {
                        "name": "Account #3",
                        "network": "linkedin",
                        "import_status": {
                            "code": "permanent_authentication_error",
                            "is_importing": false,
                            "last_import_started": "2018-01-01T03:15:00Z",
                            "last_import_finished": "2018-01-01T03:20:00Z",
                            "last_import_failed": null,
                            "importable": false
                        }
                    }
                ]
            }

## Discovering Metrics [/metric_descriptors]

Developers will often need to discover various data fields to request and interpret their desired advertising data.
The following endpoints and documentation comprise comprehensive list of permitted options for advertising data fields.

Broadly, AdStage separates these fields into two categories: metrics and meta fields.
A field is stored as a metric if an advertising network allows AdStage to request the data as a daily timeseries (for example, `"clicks"`).
Metric fields are discoverable through the Metric Descriptor resource, which provides information about how to interpret and present the field (for example, by maintaining a list of networks supporting that metric).
In contrast, a field is stored as metadata if an advertising network only allows AdStage to request a single value for the data (for example, `"title"`).
Meta fields do not have associated rich descriptor resources at this time.

**Note: In addition to checking metrics via the API, developers can refer to [this document](https://docs.google.com/spreadsheets/d/1jdlZuRMTkCjq2jf1MvH_I60-o1-mJ6SW8WPmeQ60jh8/edit?usp=sharing) that AdStage maintains as a metrics reference.**

### Meta Fields

Metadata fields are typically strings, such as an ad's `title`, though in some cases, a meta field can be of another type, such as `budget_float` - the most recent budget for the entity cast to a float.
In these cases, the casted data type is appended to the string: `budget_float` will return a float.

Because meta fields are so rarely changed, AdStage does not currently provide an API endpoint to list all meta fields on-demand.
Instead, a comprehensive list of metadata fields is provided below for convenience.
In the future, AdStage may replace this with an API endpoint for meta field discovery.

#### Entity Names

Gives the displayable names of each entity (e.g. an ad) or parent entity (e.g. the campaign owning the ad).
Often useful for filtering reports based on substrings of a name when ads are created with stable naming conventions.

| UI Display Name        | API Field Name          |
| ---------------------- | ----------------------- |
| Network                | `network`               |
| Name                   | `name`                  |
| Account Name           | `account_name`          |
| Campaign Name          | `campaign_name`         |
| Ad Group / Ad Set Name | `ad_group_name`         |
| Ad Name                | `ad_name`               |

#### Currency Information

Gives the metadata needed to interpret currency metrics, such as spend, associated with the entity.

| UI Display Name        | API Field Name          |
| ---------------------- | ----------------------- |
| Currency Code          | `currency_code`         |
| Currency Symbol        | `currency_symbol`       |

#### Short IDs

Gives short form unique identifiers for each entity, matching ids generated by each remote ad network.
Prefer the more descriptive long form IDs for cases where a human may need to interpret the IDs.
For example, AdStage internally chooses the `entity_id` field as the main search field in its troubleshooting utilities.

| UI Display Name        | API Field Name          |
| ---------------------- | ----------------------- |
| Account ID             | `remote_account_id`     |
| Campaign ID            | `remote_campaign_id`    |
| Ad Group ID            | `remote_ad_group_id`    |
| Ad ID                  | `remote_ad_id`          |
| Keyword ID             | `remote_keyword_id`     |

#### Account Groups and Folders IDs

Gives short form unique identifiers for entity grouping constructs managed within the AdStage UI.
Folders represent groups of campaigns, and Account Groups represent groups of accounts.
The ID of the user who created the folder is used to complete the field.
Use the `GET /me` endpoint to get the current user ID.

| UI Display Name        | API Field Name                 | Example           |
| ---------------------- | ------------------------------ | ----------------- |
| Account Group ID       | `account_group_id`             |                   |
| Account Group Name     | `account_group_name`           |                   |
| Folder Name            | `folder_names.{id}`            | `folder_names.40` |
| Folder ID              | `folder_ids.{id}`              | `folder_ids.40`   |

*Note that `folder_names` and `folder_ids` will automatically infer your the requesting user's ID, though data will still be returned under the fully qualified field name (e.g. a request for `folder_names` might list results under `folder_names.40`).*

#### Long IDs

Gives long form unique identifiers for each entity, matching ids generated by each remote network.
Note that `id`, while still maintained, refers to a legacy identification strategy that AdStage no longer uses, and therefore may be deprecated in the future.
Prefer the `entity_id` variants instead for uniquely identifying ads in application logic.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| ID                     | `id`                           |
| Entity ID              | `entity_id`                    |
| Account Entity ID      | `account_entity_id`            |
| Campaign Entity ID     | `campaign_entity_id`           |
| Ad Group Entity ID     | `ad_group_entity_id`           |
| Ad Entity ID           | `ad_entity_id`                 |
| Keyword Entity ID      | `keyword_entity_id`            |

#### Entity Statuses

Gives the latest known status of the entity on the remote network (e.g. `COMPLETED`).
Note that the status does not necessarily correspond with the serving status.
For example, an ad marked "ACTIVE" may not be serving if its campaign is marked "INACTIVE".

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Status                 | `status`                       |
| Account Status         | `account_status`               |
| Campaign Status        | `campaign_status`              |
| Ad Group Status        | `ad_group_status`              |
| Ad Status              | `ad_status`                    |
| Keyword Status         | `keyword_status`               |

#### Bid Information

Gives information regarding the bid on an entity.
Note that `bid_float` and `bid.value` represent the same data as a float and string respectively.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Bid                    | `bid_float`                    |
| Pretty Bid             | `bid.pretty_bid`               |
| Bid Title              | `bid.title`                    |
| Bid Subtitle           | `bid.subtitle`                 |
| Bid Type               | `bid.type`                     |
| Bid Value              | `bid.value`                    |

#### Budget Information

Gives information regarding the budget for an entity.
Note that `budget_float` and `budget.value` represent the same data as a float and string respectively.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Budget                 | `budget_float`                 |
| Pretty Budget          | `budget.pretty_budget`         |
| Budget Title           | `budget.title`                 |
| Budget Subtitle        | `budget.subtitle`              |
| Budget Type            | `budget.type`                  |
| Budget Value           | `budget.value`                 |

#### Objective Information

Gives information regarding the objective for an entity.
Note that AdStage stores these related fields formatted as JSON in the `objective` object.
To request a single, flattened objective field, append a dot and the key name, such as `objective.unit`.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Objective              | `objective`                    |
| Objective Code         | `objective.code`               |
| Objective Title        | `objective.title`              |
| Objective Subtitle     | `objective.subtitle`           |
| Objective Unit         | `objective.unit`               |

#### Entity Types

Gives information about the type or subtype for an entity as designated by the remote network.
For example, a LinkedIn campaign may have the `campaign_type` of `SSU`, a LinkedIn API designated campaign type.
Note that the `type` field is an exception and refers to an AdStage generated entity category, such as `network_ad`, rather than a remote network designated category.
See the Entity IDs section for more information.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Type                   | `type`                         |
| Campaign Type          | `campaign_type`                |
| Ad Type                | `ad_type`                      |
| Match Type             | `keyword_match_type`           |

#### Keyword/Criterion Information

Gives information describing a keyword or criterion.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Keyword Text           | `keyword_text`                 |
| Quality Score          | `quality_score_float`          |

#### Ad Information

Gives information describing an ad.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Ad Title               | `title`                        |
| Ad Headline            | `ad_headline`                  |
| Ad Description         | `description`                  |
| Update                 | `update`                       |
| Post Text              | `post_text`                    |

#### URL Information

Gives information about various URLs associated with an ad.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| Destination URL        | `destination_url`              |
| Final URL              | `final_url`                    |
| Final Mobile URL       | `final_mobile_url`             |
| Image                  | `image_url`                    |
| SU Image               | `submitted_image_url`          |
| Tracking Template      | `tracking_url_template`        |

#### UTM Tracking Information

**Note: UTM tracking information is only available if AdStage Join has been added to your AdStage plan and a Join task has been completed for the entity.
Currently, Join is available only as a paid Add-On.**

Gives information about the UTM parameters associated with the entity.
Note that AdStage stores these parameters formatted as JSON in `tracking_params`.
To request a single, flattened parameter, append a dot and the key name, such as `tracking_params.utm_term`.

| UI Display Name        | API Field Name                 |
| ---------------------- | ------------------------------ |
| URL Tracking Params    | `tracking_params`              |
| UTM Medium             | `tracking_params.utm_medium`   |
| UTM Source             | `tracking_params.utm_source`   |
| UTM Campaign           | `tracking_params.utm_campaign` |
| UTM Content            | `tracking_params.utm_content`  |
| UTM Term               | `tracking_params.utm_term`     |

### Metric Descriptors [GET]

This endpoint provides information on the names and formats of cross-channel (`adstage` provider) metrics available in AdStage's reporting endpoints.

+ Request

    + Headers

            Accept: application/json

+ Response 200

    A list of columns that are available to pull via the reporting endpoint.

    + Attributes

        + descriptors (array)
            + (object)
                + id: "clicks" (string) - the identifier assigned to the metric in reports
                + short_name: "Clicks" (string) - a short human readable name for the metric
                + name: "Clicks" (string) - the full human readable name for the metric
                + tooltip: "Clicks shows how many times a user clicked on your ad" (string) - additional details about a metric, if available
                + format: "DEFAULT", "PERCENTAGE", "CURRENCY", "TEXT", "DECIMAL", "INTEGER" (enum[string]) - format for the metric (default is `INTEGER`)
                + type: "METRIC", "TEXT" (enum[string]) - whether the descriptor is for a metric or metadata
                + `is_adwords`: true (boolean) - if the metric is valid for the `adwords` network
                + `is_amazon`: true (boolean) - if the metric is valid for the `amazon` network
                + `is_bing_ads`: true (boolean) - if the metric is valid for the `bing_ads` network
                + `is_facebook`: true (boolean) - if the metric is valid for the `facebook` network
                + `is_gemini`: false (boolean) - if the metric is valid for the `gemini` network
                + `is_google_analytics`: false (boolean) - if the metric is valid for the `google_analytics` network
                + `is_linkedin`: true (boolean) - if the metric is valid for the `linkedin` network
                + `is_pinterest`: true (boolean) - if the metric is valid for the `pinterest` network
                + `is_quora`: true (boolean) - if the metric is valid for the `quora` network
                + `is_spotify`: true (boolean) - if the metric is valid for the `spotify` network
                + `is_twitter`: true (boolean) - if the metric is valid for the `twitter` network
                + `is_account`: true (boolean) - if the metric is valid for the account reporting level
                + `is_campaign`: true (boolean) - if the metric is valid for the campaign reporting level
                + `is_ad_group`: true (boolean) - if the metric is valid for the ad group reporting level
                + `is_ad`: true (boolean) - if the metric is valid for the ad reporting level
                + `is_keyword`: true (boolean) - if the metric is valid for keyword reporting level

    + Body

            [
                {
                    "id": "clicks",
                    "short_name": "Clicks",
                    "name": "Clicks",
                    "is_default": true,
                    "tooltip": "<b>Clicks</b> show how many times your ads have been clicked.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                }, {
                    "id": "impressions",
                    "short_name": "Impr.",
                    "name": "Impressions",
                    "is_default": true,
                    "tooltip": "<b>Impressions</b> show how many times your ads have been shown.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                }, {
                    "id": "ctr",
                    "short_name": "CTR",
                    "name": "CTR",
                    "is_default": true,
                    "tooltip": "<b>Clickthrough rate</b> shows how often people who saw your ad ended up clicking it.<br><br> CTR is clicks divided by impressions.<br><br> To improve your CTR, check out our <a href=\"http://blog.adstage.io/2013/05/23/5-tips-for-creating-effective-ppc-ads/\" target=\"_blank\">5 tips for creating effective ads</a>.",
                    "format": "PERCENTAGE",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                }
            ]

### Network Metric Descriptors [GET /metric_descriptors/{network}]

This endpoint provides information on the names and formats of metrics from external providers available in AdStage's V1 reporting endpoint.

Note that metric descriptors from non-AdStage reporting providers are currently considered separate from AdStage provider metric descriptors.
Descriptors may share the same `id` across providers but not necessarily associate to the same metrics (for example, the `clicks` metric from `facebook` provider reports actually matches the `total_clicks` metric in `adstage` provider reports).
Developers should therefore take care to maintain separate metric descriptor lists for each reporting provider accessed through the AdStage API.
Additionally, non-AdStage network provider metrics do not distinguish between meta and metric fields; instead, any response from this endpoint will include meta fields in the metric descriptors list (typically as `"TEXT"` type).

+ Parameters

    + network: facebook (string)

        Which network you want descriptors for. Currently `"facebook"`, `"adwords"`, `"gemini"`, and `"google_analytics"` are supported.

+ Request

    + Headers

            Accept: application/json

+ Response 200

    A list of columns that are available to pull via the reporting endpoint.

    + Attributes

        + descriptors (array)
            + (object)
                + id: "clicks" (string) - the identifier assigned to the metric in reports
                + `short_name`: "Clicks" (string) - a short human readable name for the metric
                + `display_names`: ["Clicks"] (array[string]) - the network's list of allowable human readable display names for the metric; this key is omitted unless `adwords` was specified for the `network` param
                + name: "Clicks" (string) - the full human readable name for the metric used in AdStage UIs
                + tooltip: "Clicks shows how many times a user clicked on your ad" (string) - additional details about a metric, if available
                + format: "DEFAULT", "PERCENTAGE", "CURRENCY", "TEXT", "DECIMAL", "INTEGER" (enum[string]) - format for the metric (default is `INTEGER`)
                + type: "METRIC", "TEXT" (enum[string]) - whether the descriptor is for a metric or metadata
                + `can_filter`: true (boolean) - if the metric is allowed to be used in a filter field for a reporting request; this key is omitted unless `gemini` was specified for the `network` param
                + supports_filters: ["ACCOUNT_PERFORMANCE_REPORT"] (array[string]) - a list of all reports on the provider's network that allow filtering on the metric; this key is omitted unless `adwords` was specified for the `network` param
                + supports_zero_impressions: ["ACCOUNT_PERFORMANCE_REPORT"] (array[string]) - a list of all reports on the provider's network that maintain metrics even when the ad entity has not logged any impressions; this key is omitted unless `adwords` was specified for the `network` param
                + reports: ["ACCOUNT_PERFORMANCE_REPORT"] (array[string]) - a list of all reports on the provider's network that provide data for the metric; this key is omitted unless `adwords` was specified for the `network` param
                + `is_adwords`: true (boolean) - if the metric is valid for the `adwords` network
                + `is_amazon`: true (boolean) - if the metric is valid for the `amazon` network
                + `is_bing_ads`: true (boolean) - if the metric is valid for the `bing_ads` network
                + `is_facebook`: true (boolean) - if the metric is valid for the `facebook` network
                + `is_gemini`: false (boolean) - if the metric is valid for the `gemini` network
                + `is_google_analytics`: false (boolean) - if the metric is valid for the `google_analytics` network
                + `is_linkedin`: true (boolean) - if the metric is valid for the `linkedin` network
                + `is_pinterest`: true (boolean) - if the metric is valid for the `pinterest` network
                + `is_quora`: true (boolean) - if the metric is valid for the `quora` network
                + `is_spotify`: true (boolean) - if the metric is valid for the `spotify` network
                + `is_twitter`: true (boolean) - if the metric is valid for the `twitter` network
                + `is_account`: true (boolean) - if the metric is valid for the account reporting level
                + `is_campaign`: true (boolean) - if the metric is valid for the campaign reporting level
                + `is_ad_group`: true (boolean) - if the metric is valid for the ad group reporting level
                + `is_ad`: true (boolean) - if the metric is valid for the ad reporting level
                + `is_keyword`: true (boolean) - if the metric is valid for keyword reporting level

    + Body

            [
                {
                    "id": "reach",
                    "short_name": "Reach",
                    "name": "Reach",
                    "is_default": true,
                    "tooltip": "The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": false,
                    "is_amazon": false,
                    "is_bing_ads": false,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": false,
                    "is_pinterest": false,
                    "is_quora": false,
                    "is_spotify": false,
                    "is_twitter": false,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": false,
                    "is_post": false,
                    "is_company_status_update": false,
                    "show_increase_as": "POSITIVE"
                },
                {
                    "id": "results",
                    "short_name": "Results",
                    "name": "Results",
                    "is_default": true,
                    "tooltip": "The number of outcomes you achieved in your ad campaign, based on the objective you selected.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": false,
                    "is_amazon": false,
                    "is_bing_ads": false,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": false,
                    "is_pinterest": false,
                    "is_quora": false,
                    "is_spotify": false,
                    "is_twitter": false,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": false,
                    "is_post": false,
                    "is_company_status_update": false,
                    "show_increase_as": "POSITIVE"
                }
            ]

## Building Reports [/organizations/{org_id}/build_report]

Use this endpoint to pull reports at any level of reporting available within AdStage, or to conveniently pull real-time reports with the same normalization scheme from supported external API providers such as Facebook Direct.
**The V1 endpoint does not support reporting on calculated metrics; choose the V2 endpoint if that feature is required.**

### Basic Report [POST /organizations/{org_id}/build_report]

This type of report will return one row per requested entity with metrics aggregated across the requested timeframe.

+ Parameters

    + org_id (number)
        The fetch id for the organization owning the entities that will be reported on.

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `entity_level`: "accounts", "campaigns", "ad_groups", "ads", "keywords" (enum, required)

            which entity level of report you want to fetch (`"accounts"`, `"campaigns"`, 
            `"ad_groups"`, `"ads"`, `"keywords"`)

        + `date_range`: "last 30 days" (string, required)

            An AdStage date range string.
            See the Date Ranges section for details about allowed date range formats.

        + limit: 10 (number) - number of rows to include
        + `sort_by`: "clicks" (string) - metric name/meta name to sort by
        + order: "desc" (string) - sort either ascending (`"asc"`) or descending (`"desc"`)
        + `group_by`: "network" (string) - if supplied, metrics will be grouped by this meta key

        + `aggregate_by`: "day" (string) - if supplied, will get a Time Series Report instead.
        + networks: "adwords" (string) - list of networks to include in the result, can be array, single value, or comma-separated list
        + statuses: "all_visible" (string)
            filter based on entity status codes

            * `all_visible` includes Active, Paused, and Completed entities (this is the default option)
            * `all_active` includes Active entities
            * `all_inactive` includes Paused and Completed entities
            * `all_with_deleted` includes Active, Paused, Completed, Archived, and Deleted entities

        + filters (array) - a set of filters to limit the results by (AND conditions)

            + (object) - filter object
                + path: "meta/campaign_name" (string) - metric name or meta name prefixed with `"meta/"`
                + value: 5 - a number, string or array, depending on operator 
                + op (enum)
                    + "gt" - greater than
                    + "lt" - less than
                    + "gte" - greater than or equal
                    + "lte" - less than or equal
                    + "in" - exact match to one of the values provided in the filter
                    + "iin" - case-insensitive match for one of the values provided in the filter
                    + "match" - case-sensitive string matching
                    + "nomatch" - case-sensitive string NOT matching
                    + "imatch" - case-insensitive string matching
                    + "inomatch" - case-insensitive string NOT matching


        + fields: "clicks", "spend", "impressions" (array) - optional list of metrics or meta fields to include in the result (see instructions on listing metrics descriptors to obtain an up-to-date list from the API). If fields are not requested, a selection of the most commonly requested fields will be returned in the report.
        + query (object) - Dynamically includes or excludes fields in the response. Set to true to include all available metadata, or pick and choose specific keys to show with an object. For example:
            ```
            {"_embedded
              {"adstage:metrics/totals": {"data": true}}}
            ```
        + provider: "adstage" (string)
            To pull reports from other sources, you can set this to a source name.
            The default is "adstage", which relies on data imported into AdStage.
            External providers are also supported:
            "facebook" requires `"targets"` to be set to a single Facebook account,
            "adwords" requires `"targets"` to be set to a single Google Ads account,
            "gemini" requires `"targets"` to be set to a single Gemini account (beta access only),
            and `"google_analytics"` requires `"targets"` to be set to a single GA Profile.

        + targets: "/network/adstage/user/292", "/network/adstage/folder/5555", "/network/adstage/account_group/333", "/network/adwords/account/2332" (array)
            Optional list of AdStage Entity IDs to pull a report for; if omitted, all data available for the organization will be used.
            This can be a list of accounts, account groups, folders, or campaigns.

        + dimensions (array)
            Only available if you use a non-AdStage provider - a list of dimension names to break a report by.

            * `facebook` provider dimensions here: [Insights breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns/v2.9#ageandgender)
            * `adwords` provider dimensions change by report, described here: [Google Ads Reports](https://developers.google.com/adwords/api/docs/appendix/reports)
            * `gemini` provider dimensions change by report (described as cubes) - details: [Reporting > Cubes](https://developer.yahoo.com/gemini/guide/reporting/cubes/)

        + `relative_to`: "America/Los_Angeles" (string)
            NOTE: This parameter is deprecated but supported for compatibility; prefer `relative_to_time_zone` and/or `relative_to_datetime` for new requests.
            An ISO 8601 short date or datetime string without time zone or UTC offset (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`); or a TZ Info time zone string (such as `America/Los_Angeles`).
            When a date is provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When a time zone is provided, the request's `date_range` parameter will be interpreted as the actual current moment, set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.

        + `relative_to_datetime`: "2020-03-14" (string)
            An ISO 8601 short date or datetime string, with or without UTC offset (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, or `YYYY-MM-DDTHH:MM:SS±HH:MM`).
            When provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When omitted, requests will assume midnight of the current day.

        + `relative_to_time_zone`: "America/Los_Angeles" (string)
            A TZ Info time zone string (such as `America/Los_Angeles`).
            When provided, the request's `date_range` parameter will be set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.
            When combined with the `relative_to_datetime` parameter, that datetime will converted to its equivalent in this time zone.
            When omitted, requests will assume UTC.

    + Body

            {
                "entity_level": "campaigns",
                "date_range": "last 30 days",
                "fields": ["clicks", "spend", "campaign_name", "remote_campaign_id", "network"]
            }

+ Response 200 (application/json)

    + Attributes

        + `_embedded`
            - `adstage:metrics` (array) - list of report rows (if `"aggregate_by"` is set, will return `"adstage:time_series"` instead)
                - (object)
                    - data (object) - key-value pairs of metric identifiers to floats
                    - meta (object) - key-value pairs of metadata names to strings or objects
            - `adstage:metrics/totals` (object) - totals row for the result
                - data (object) - key-value pairs of metric identifiers to floats
                - meta (object) - key-value pairs of metadata names to arrays of unique values in the results


    + Body

            {
                "_embedded": {
                    "adstage:metrics": [
                        {
                            "data": {
                                "clicks": 1014,
                                "spend": 339.460006713867
                            },
                            "timeframe": {
                                "start": "2016-12-22T00:00:00Z",
                                "end": "2017-01-20T23:59:59Z"
                            },
                            "meta": {
                                "campaign_name": "Display - US - Gmail Ads v2",
                                "entity_id": "/network/adwords/campaign/735025362",
                                "remote_campaign_id": "735025362",
                                "network": "adwords",
                                "currency_code": "USD",
                                "currency_symbol": "$",
                                "row_name": "Display - US - Gmail Ads v2"
                            }
                        }
                    ],
                    "adstage:metrics/totals": {
                        "id": "totals",
                        "data": {
                            "clicks": 8783,
                            "spend": 23780.8718175292
                        },
                        "timeframe": {
                            "start": "2016-12-01T00:00:00Z",
                            "end": "2017-01-31T23:59:59Z"
                        },
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$",
                            "series_name": "All"
                        }
                    }
                },
                "counts": {
                    "overall": 73262,
                    "filtered_buckets": 11820,
                    "page": 10,
                    "filtered": 11820,
                    "overall_buckets": 73262
                },
                "_links": {
                    "next": {
                        "href": "https://platform.adstage.io/api/organizations/40/build_report?date_range=2016-12-24..2017-01-22&entity_level=campaigns&fields=clicks%2Cspend%2Ccampaign_name%2Cremote_campaign_id%2Cnetwork&limit=10&networks=adwords%2Cbing_ads%2Cfacebook%2Clinkedin%2Ctwitter&offset=10&order=desc&provider=adstage&sort_by=clicks&statuses=active%2Cad_group_inactive%2Ccampaign_inactive%2Ccompleted%2Cempty%2Cinactive%2Cnot_empty"
                    },
                    "last": {
                        "href": "https://platform.adstage.io/api/organizations/40/build_report?date_range=2016-12-24..2017-01-22&entity_level=campaigns&fields=clicks%2Cspend%2Ccampaign_name%2Cremote_campaign_id%2Cnetwork&limit=10&networks=adwords%2Cbing_ads%2Cfacebook%2Clinkedin%2Ctwitter&offset=11810&order=desc&provider=adstage&sort_by=clicks&statuses=active%2Cad_group_inactive%2Ccampaign_inactive%2Ccompleted%2Cempty%2Cinactive%2Cnot_empty"
                    }
                }
            }

### Time Series Report [POST /organizations/{org_id}/build_report]

This type of report will return one row per requested entity with metrics broken into a series of day, week, or month datapoints.
The request is the same as a standard report but using the `"aggregate_by"` option to change the format of the returned data.

+ Parameters

    + org_id (number)
        The fetch id for the organization owning the entities that will be reported on.

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `entity_level`: "accounts", "campaigns", "ad_groups", "ads", "keywords" (enum, required)

            which entity level of report you want to fetch (`"accounts"`, `"campaigns"`, 
            `"ad_groups"`, `"ads"`, `"keywords"`)

        + `aggregate_by`: "day", "week", "month" (enum) - the level of detail to include in the time series
        + `date_range`: "last 30 days" (string, required)

            An AdStage date range string.
            See the Date Ranges section for details about allowed date range formats.

        + limit: 10 (number) - number of rows to include
        + `sort_by`: "clicks" (string) - metric name/meta name to sort by
        + order: "desc" (string) - sort either ascending (`"asc"`) or descending (`"desc"`)
        + `group_by`: "network" (string) - if supplied, metrics will be grouped by this meta key
        + networks: "adwords" (string) - list of networks to include in the result, can be array, single value, or comma-separated list
        + statuses: "all_visible" (string)
            filter based on entity status codes

            * `all_visible` includes Active, Paused, and Completed entities (this is the default option)
            * `all_active` includes Active entities
            * `all_inactive` includes Paused and Completed entities
            * `all_with_deleted` includes Active, Paused, Completed, Archived, and Deleted entities

        + filters (array) - a set of filters to limit the results by (AND conditions)

            + (object) - filter object
                + path: "meta/campaign_name" (string) - metric name or meta name prefixed with `"meta/"`
                + value: 5 - a number, string or array, depending on operator 
                + op (enum)
                    + "gt" - greater than
                    + "lt" - less than
                    + "gte" - greater than or equal
                    + "lte" - less than or equal
                    + "in" - exact match to one of the values provided in the filter
                    + "iin" - case-insensitive match for one of the values provided in the filter
                    + "match" - case-sensitive string matching
                    + "nomatch" - case-sensitive string NOT matching
                    + "imatch" - case-insensitive string matching
                    + "inomatch" - case-insensitive string NOT matching

        + fields: "clicks", "spend", "impressions" (array) - optional list of fields to include in the result. If fields are not requested, all possible fields will be returned in the report.
        + query (object) - Dynamically includes or excludes fields in the response. Set to true to include all available metadata, or pick and choose specific keys to show with an object. For example:
            ```
            {"_embedded
                {"adstage:time_series/totals": {"data": true}}}
            ```
        + provider: "adstage" (string)
            To pull reports from other sources, you can set this to a source name.
            The default is "adstage", which relies on data imported into AdStage.
            External providers are also supported:
            "facebook" requires `"targets"` to be set to a single Facebook account,
            "adwords" requires `"targets"` to be set to a single Google Ads account,
            "gemini" requires `"targets"` to be set to a single Gemini account (beta access only),
            and `"google_analytics"` requires `"targets"` to be set to a single GA Profile.

        + targets: "/network/adstage/user/292", "/network/adstage/folder/5555", "/network/adstage/account_group/333", "/network/adwords/account/2332" (array)
            Optional list of AdStage Entity IDs to pull a report for; if omitted, all data available for the organization will be used.
            This can be a list of accounts, account groups, folders, or campaigns.

        + dimensions (array)
            Only available if you use a non-AdStage provider - a list of dimension names to break a report by.

            * `facebook` provider dimensions here: [Insights breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns/v2.9#ageandgender)
            * `adwords` provider dimensions change by report, described here: [Google Ads Reports](https://developers.google.com/adwords/api/docs/appendix/reports)
            * `gemini` provider dimensions change by report (described as cubes) - details: [Reporting > Cubes](https://developer.yahoo.com/gemini/guide/reporting/cubes/)

        + `relative_to`: "America/Los_Angeles" (string)
            NOTE: This parameter is deprecated but supported for compatibility; prefer `relative_to_time_zone` and/or `relative_to_datetime` for new requests.
            An ISO 8601 short date or datetime string without time zone or UTC offset (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`); or a TZ Info time zone string (such as `America/Los_Angeles`).
            When a date is provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When a time zone is provided, the request's `date_range` parameter will be interpreted as the actual current moment, set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.

        + `relative_to_datetime`: "2020-03-14" (string)
            An ISO 8601 short date or datetime string, with or without UTC offset (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, or `YYYY-MM-DDTHH:MM:SS±HH:MM`).
            When provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When omitted, requests will assume midnight of the current day.

        + `relative_to_time_zone`: "America/Los_Angeles" (string)
            A TZ Info time zone string (such as `America/Los_Angeles`).
            When provided, the request's `date_range` parameter will be set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.
            When combined with the `relative_to_datetime` parameter, that datetime will converted to its equivalent in this time zone.
            When omitted, requests will assume UTC.

    + Body

            {
                "entity_level": "campaigns",
                "aggregate_by": "day",
                "date_range": "last 30 days",
                "fields": ["clicks", "spend", "campaign_name", "remote_campaign_id", "network"]
            }

+ Response 200 (application/json)

    + Attributes

        + `_embedded`
            - `adstage:time_series` (array) - list of report time series rows (if `"aggregate_by"` is not set, see `"adstage:metrics"`)
                - (object)
                    - series (array) - datapoints separated by aggregation
                        - (object)
                            - timeframe
                                + start
                                + end
                            - data (object) - key-value pairs of metric identifiers to floats
                    - data (object) - totals for the requested timeseries metrics
                    - meta (object) - key-value pairs of metadata names to strings or objects
            - `adstage:time_series/totals` (object) - totals row for the result if `"aggregate_by"` set
                - data (object) - totals for the requested timeseries metrics
                - series (array)

                    - (object)
                        - timeframe
                            + start
                            + end
                        - data (object) - key-value pairs of metric identifiers to floats

                - meta (object) - key-value pairs of metadata names to arrays of unique values in the results




    + Body

            {
                "_embedded": {
                    "adstage:time_series": [
                        {
                            "id": "production.1.accounts.bing_ads.2982670.campaigns.53744320",
                            "data": {
                                "clicks": 1458,
                                "spend": 2715.01000976562
                            },
                            "series": [
                                {
                                    "data": {
                                        "clicks": 829,
                                        "spend": 1549.68005371094
                                    },
                                    "timeframe": {
                                        "start": "2016-12-01T00:00:00Z",
                                        "end": "2016-12-31T23:59:59Z"
                                    }
                                },
                                {
                                    "data": {
                                        "clicks": 629,
                                        "spend": 1165.32995605469
                                    },
                                    "timeframe": {
                                        "start": "2017-01-01T00:00:00Z",
                                        "end": "2017-01-31T23:59:59Z"
                                    }
                                }
                            ],
                            "timeframe": {
                                "start": "2016-12-01T00:00:00Z",
                                "end": "2017-01-31T23:59:59Z"
                            },
                            "meta": {
                                "campaign_name": "Search - US - Nonbrand - Facebook Ads Jacob",
                                "remote_campaign_id": "53744320",
                                "entity_id": "/network/bing_ads/campaign/53744320",
                                "network": "bing_ads",
                                "currency_code": "USD",
                                "currency_symbol": "$",
                                "series_name": "Search - US - Nonbrand - Facebook Ads Jacob"
                            }
                        }
                    ],
                    "adstage:time_series/totals": {
                        "id": "totals",
                        "data": {
                            "clicks": 8783,
                            "spend": 23780.8718175292
                        },
                        "series": [
                            {
                                "data": {
                                    "clicks": 4025,
                                    "spend": 11414.1101390719
                                },
                                "timeframe": {
                                    "start": "2016-12-01T00:00:00Z",
                                    "end": "2016-12-31T23:59:59Z"
                                }
                            },
                            {
                                "data": {
                                    "clicks": 4758,
                                    "spend": 12366.7616784573
                                },
                                "timeframe": {
                                    "start": "2017-01-01T00:00:00Z",
                                    "end": "2017-01-31T23:59:59Z"
                                }
                            }
                        ],
                        "timeframe": {
                            "start": "2016-12-01T00:00:00Z",
                            "end": "2017-01-31T23:59:59Z"
                        },
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$",
                            "series_name": "All"
                        }
                    }
                },
                "counts": {
                    "overall": 73262,
                    "filtered_buckets": 11820,
                    "page": 10,
                    "filtered": 11820,
                    "overall_buckets": 73262
                },
                "_links": {
                    "next": {
                        "href": "https://platform.adstage.io/api/organizations/40/build_report?aggregate_by=month&date_range=2016-12-24..2017-01-22&entity_level=campaigns&fields=clicks%2Cspend%2Ccampaign_name%2Cremote_campaign_id%2Cnetwork&limit=10&networks=adwords%2Cbing_ads%2Cfacebook%2Clinkedin%2Ctwitter&offset=10&order=desc&provider=adstage&sort_by=clicks&statuses=active%2Cad_group_inactive%2Ccampaign_inactive%2Ccompleted%2Cempty%2Cinactive%2Cnot_empty"
                    },
                    "last": {
                        "href": "https://platform.adstage.io/api/organizations/40/build_report?aggregate_by=month&date_range=2016-12-24..2017-01-22&entity_level=campaigns&fields=clicks%2Cspend%2Ccampaign_name%2Cremote_campaign_id%2Cnetwork&limit=10&networks=adwords%2Cbing_ads%2Cfacebook%2Clinkedin%2Ctwitter&offset=11810&order=desc&provider=adstage&sort_by=clicks&statuses=active%2Cad_group_inactive%2Ccampaign_inactive%2Ccompleted%2Cempty%2Cinactive%2Cnot_empty"
                    }
                }
            }

## Custom Conversions [/organizations/{org_id}/metric_descriptors]

The AdStage custom metric descriptor endpoint will allow data to be uploaded to a custom column for any existing entities stored within AdStage.
You can then use these custom conversion columns in the reporting endpoints or in the AdStage product.
This requires a few steps to get data flowing:

### Step 1. Create a custom metric descriptor [POST /organizations/{org_id}/metric_descriptors]

Creates a custom metric descriptor to allow data upload and returns the URL which will accept metric data for the new descriptor.
This step only needs to be performed once per conversion column - the metric descriptor can be reused across multiple data uploads.
To get a list of existing conversion columns, see the Discovering Metrics section.

+ Parameters

    + `org_id` (number) - The fetch id of the user's organization.

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `name`: "Sales Leads: A+" (string, required) - full name of the conversion column
        + `short_name`: "A+ Leads" (string, required) - a shorter version of name for table column headers
        + `tooltip`: "Leads scored A+ in Salesforce" (string, required) - a text description of the converion for use in tooltips in AdStage products

    + Body

            {
                "name": "Sales Leads: A+",
                "short_name": "A+ Leads",
                "tooltip": "Leads scored A+ in Salesforce"
            }

+ Response 201

    Note that in the response, the id is returned as `custom_conversions:{fetch_id}:conversions`.
    You can use the link to find the appropriate URL for upload in Step 2 of the conversion upload process.

    + Attributes

        + id: "custom_conversions:14:conversions" (string) - the raw metric id returned in reports (see the Building Reports section)
        + `_links` (object)
            + `adstage:custom_conversion_upload` (object)
                + href: "https://platform.adstage.io/api/organizations/40/metric_descriptors/14/conversions" (string) - the URL for uploading data in step 2.

    + Body

            {
                "id": "custom_conversions:14:conversions",
                "category": "CUSTOM_CONVERSION",
                "type": "METRIC",
                "name": "Sales Leads: A+",
                "short_name": "A+ Leads",
                "tooltip": "Doesn't matter",
                "default_sort_order": "DESC",
                "format": "DEFAULT",
                "_links": {
                    "adstage:custom_conversion_upload": {
                        "href": "https://platform.adstage.io/api/organizations/40/metric_descriptors/14/conversions"
                    }
                }
            }

### Step 2. Post metrics data for the custom metric descriptor [POST /organizations/{org_id}/metric_descriptors/{descriptor_id}/conversions]

Uploads conversion data to associate it with a custom metric descriptor.

This endpoint does not support automatic "roll up" of conversions to their parent entities.
To roll up values, for example from campaigns to their accounts, include both the campaign ids and the account ids in the `"attribution"` map.
Alternatively, the V2 endpoint implements an automatic roll up feature.

+ Parameters

    + `org_id` (integer) - the fetch id of the user's organization
    + `descriptor_id` (integer) - the fetch id of the metric descriptor

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `conversions` (array, required) - a list of conversions
            + (object)
                + `timestamp`: `"2016-02-03T03:40Z"` (string, required) - ISO8061 formatted string representing when the conversion occurred.
                + `value`: 30.5 (number) - An optional conversion value, expressed in the currency type for the converting account. Used to compute Return on Ad Spend.
                + `attribution` - A list of key/value pairs where the key is an AdStage Entity ID and the value is a multiplier of how much to weigh the conversion. Use 1 unless you want to do multi-touch attribution modeling.
                    + `/network/adwords/campaign/530303`: 1 (number) - (this id is just an example; use valid ids)
                    + `/network/adwords/acount/530303`: 1 (number) - (this id is just an example; use valid ids)

        + `date_range`: `"last 30 days"` (string, required)

            An AdStage date range string.
            See the Date Ranges section for details about allowed date range formats.

    + Body

            {
                "conversions": [
                    {"timestamp": "2016-11-11T06:00Z", "value": 35.0, "attribution": {"/network/adwords/campaign/143365350": 1, "/network/adwords/account/143365350": 1}},
                    {"timestamp": "2016-11-11T07:00Z", "value": 41.25, "attribution": {"/network/adwords/campaign/143365350": 0.5, "/network/adwords/campaign/143365350": 0.5}},
                    {"timestamp": "2016-11-11T07:30Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-11T08:00Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-11T08:40Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-12T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-13T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-14T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-15T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-16T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-17T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}}
                ],
                "date_range": "2016-11-11..2016-11-17"
            }

+ Response 201

### Retrieve Organization Metric Descriptors [GET /organizations/{org_id}/metric_descriptors]

This endpoint returns information about the names and formats of custom metrics created for a single organization.

These metric descriptors can be:
* (AdStage) Custom Conversions, describing user-uploaded custom data.
* Network Custom Conversions, describing conversion data imported from supported remote netwokrs (currently Facebook and LinkedIn).
* Calculated Metrics, describing user-defined combinations of other metrics (not supported in the V1 reporting endpoint).

Additionally, AdStage will automatically derive several metrics that are listed in this endpoint based on both AdStage and Network Custom Conversions:
* Conversion Value
* Cost per Conversion
* Conversion Rate
* Return on Ad Spend (ROAS)

+ Parameters

    + org_id: 40 (string)

        Which organization you want descriptors for.

+ Request

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

+ Response 200

    A list of columns that are available to pull via the reporting endpoint.

    + Attributes

        + `descriptors` (array)
            + (object)
                + id: "clicks" (string) - the identifier assigned to the metric in reports
                + `short_name`: "Clicks" (string) - a short human readable name for the metric
                + name: "Clicks" (string) - the full human readable name for the metric
                + tooltip: "Clicks shows how many times a user clicked on your ad" (string) - additional details about a metric, if available
                + format: "DEFAULT", "PERCENTAGE", "CURRENCY", "TEXT", "DECIMAL", "INTEGER" (enum[string]) - format for the metric (default is `INTEGER`)
                + type: "METRIC", "TEXT" (enum[string]) - whether the descriptor is for a metric or metadata
                + `is_adwords`: true (boolean) - if the metric is valid for the `adwords` network
                + `is_amazon`: true (boolean) - if the metric is valid for the `amazon` network
                + `is_bing_ads`: true (boolean) - if the metric is valid for the `bing_ads` network
                + `is_facebook`: true (boolean) - if the metric is valid for the `facebook` network
                + `is_gemini`: false (boolean) - if the metric is valid for the `gemini` network
                + `is_google_analytics`: false (boolean) - if the metric is valid for the `google_analytics` network
                + `is_linkedin`: true (boolean) - if the metric is valid for the `linkedin` network
                + `is_pinterest`: true (boolean) - if the metric is valid for the `pinterest` network
                + `is_quora`: true (boolean) - if the metric is valid for the `quora` network
                + `is_spotify`: true (boolean) - if the metric is valid for the `spotify` network
                + `is_twitter`: true (boolean) - if the metric is valid for the twitter network
                + `is_account`: true (boolean) - if the metric is valid for the account reporting level
                + `is_campaign`: true (boolean) - if the metric is valid for the campaign reporting level
                + `is_ad_group`: true (boolean) - if the metric is valid for the ad group reporting level
                + `is_ad`: true (boolean) - if the metric is valid for the ad reporting level
                + `is_keyword`: true (boolean) - if the metric is valid for keyword reporting level

    + Body

            [
                {
                    "id": "clicks",
                    "short_name": "Clicks",
                    "name": "Clicks",
                    "is_default": true,
                    "tooltip": "<b>Clicks</b> show how many times your ads have been clicked.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                },
                {
                    "id": "impressions",
                    "short_name": "Impr.",
                    "name": "Impressions",
                    "is_default": true,
                    "tooltip": "<b>Impressions</b> show how many times your ads have been shown.",
                    "format": "DEFAULT",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                },
                {
                    "id": "ctr",
                    "short_name": "CTR",
                    "name": "CTR",
                    "is_default": true,
                    "tooltip": "<b>Clickthrough rate</b> shows how often people who saw your ad ended up clicking it.<br><br> CTR is clicks divided by impressions.<br><br> To improve your CTR, check out our <a href=\"http://blog.adstage.io/2013/05/23/5-tips-for-creating-effective-ppc-ads/\" target=\"_blank\">5 tips for creating effective ads</a>.",
                    "format": "PERCENTAGE",
                    "type": "METRIC",
                    "category": "PERFORMANCE",
                    "default_sort_order": "DESC",
                    "is_adwords": true,
                    "is_amazon": true,
                    "is_bing_ads": true,
                    "is_facebook": true,
                    "is_gemini": false,
                    "is_google_analytics": false,
                    "is_linkedin": true,
                    "is_pinterest": true,
                    "is_quora": true,
                    "is_spotify": true,
                    "is_twitter": true,
                    "is_account": true,
                    "is_campaign": true,
                    "is_ad_group": true,
                    "is_ad": true,
                    "is_keyword": true,
                    "is_post": null,
                    "is_company_status_update": null
                }
            ]

# Group AdStage API V2

This version of the AdStage API can be considered stable, with full release to external customers in progress.
Additional endpoints within V2 may be developed and/or released, and internal customer V2 endpoints may be documented and released to external customers in the future.

## Custom Conversions [/v2/organizations/{org_id}/metric_descriptors]

The AdStage API allows users to create and associate metrics data with Custom Conversions.
For example, a user might maintain a spreadsheet attributing Sales Qualified Leads to a mixture of ads.
With this data regularly uploaded via the API, these metrics can be blended into results from the reporting APIs and can be accessed in the AdStage product.

There are two steps required to set up a new Custom Conversion in the API:

### Step 1. Create a custom metric descriptor [POST /organizations/{org_id}/metric_descriptors]

**Note that this endpoint is identical to the V1 endpoint.
Its documentation has been copied here for convenience in explaining the custom conversion upload flow.
AdStage may choose to release a V2 namespaced endpoint with a different feature set and shape in the future.
Given this, note that the link returned from this endpoint's response refers to the V1 upload endpoint.**

Sets up a metric descriptor to allow data upload. Returns the URL to allow upload.
You only need to do this step once per conversion column you want to created.
To get a list of conversion columns, see the Build Reports section - "Organization Metric Descriptors".

+ Parameters

    + `org_id` (integer) - The fetch id of the user's organization

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `name`: "Sales Leads: A+" (string, required) - The full name of the conversion column.
        + `short_name`: "A+ Leads" (string, required) - A shorter version of name for table column headers.
        + `tooltip`: "Leads scored A+ in Salesforce" (string, required) - A text description of the converion for use in tooltips in AdStage products.

    + Body

            {
                "name": "Sales Leads: A+",
                "short_name": "A+ Leads",
                "tooltip": "Leads scored A+ in Salesforce"
            }

+ Response 201

    Note that in the response, the id is returned as `custom_conversions:{fetch_id}:conversions`.
    You can use the link to find the appropriate URL for upload in Step 2 of the conversion upload process.

    + Attributes

        + id: "custom_conversions:14:conversions" (string) - The metric name reports reports will return when providing conversion metrics for this descriptor.
        + `_links` (object)
            + `adstage:custom_conversion_upload` (object)
                + href: "https://platform.adstage.io/api/organizations/40/metric_descriptors/14/conversions" (string) - The URL for Step 2, which will accept conversion data for this metric descriptor. Note that because this endpoint is currently equivalent to the V1 endpoint, this link will point to the V1 conversion upload endpoint - if using features from the V2 endpoint, AdStage currently recommends parsing the id number from the response's `id` field, which will allow a seamless upgrade if a V2 endpoint is released, pointing to the V2 upload endpoint.

    + Body

            {
                "id": "custom_conversions:14:conversions",
                "category": "CUSTOM_CONVERSION",
                "type": "METRIC",
                "name": "Sales Leads: A+",
                "short_name": "A+ Leads",
                "tooltip": "Doesn't matter",
                "default_sort_order": "DESC",
                "format": "DEFAULT",
                "_links": {
                        "adstage:custom_conversion_upload": {
                            "href": "https://platform.adstage.io/api/organizations/40/metric_descriptors/14/conversions"
                        }
                }
            }

### Step 2. Post metrics data for the custom metric descriptor [POST /v2/organizations/{org_id}/custom_metric_descriptors/{descriptor_id}/conversions]

POST data in JSON format to this endpoint with a `"conversions"` key, a `"date_range"` key, and a `"aggregate_conversions"` key.

(See AdStage API Concepts section on Date Ranges and Entity IDs for details on those subjects)

Each conversion requires a `"timestamp"` key indicating the time of the conversion event and `"attribution"` key, which is a map of AdStage Entity IDs to weights for the conversion.
By default, we recommend using a weight of `1` for simple attribution, though other weighting schemes using different multipliers are allowed for custom multitouch attribution models.
You can also provide optional `"value"` key, indicating the currency value of the conversion.
The product of the weight and `"value"` will then determine the conversion value AdStage records from the upload, as well as any related compute values such as Return on Ad Spend.

Note that after posting conversion data to this endpoint, if a subsequent request posts different conversion data with a timestamp on the same *day* of a previously uploaded conversion's timestamp, the data will be overwritten.
For example, if `2` conversions are posted for `2016-02-03T03:40Z`, and then `1` additional conversion is posted in a new API request for `2016-02-03T04:40Z`, the entity will only display `1` conversion, not `3`.
When posting data to the endpoint, users are responsible for blending conversion data sources themselves and posting all known conversions within the same request.
Similarly, for users planning on updating conversion data over multiple requests, it is prudent to maintain a cache of previously known conversions so that the cumulative updated values can be sent in a single request, overwriting the previously updated values.

+ Parameters

    + `org_id` (integer) - The fetch id of the user's organization
    + `descriptor_id` (integer) - The fetch id of the metric descriptor

+ Request (application/json)

    + Headers

            Authorization: Bearer de4dxxxxb33f
            Accept: application/json

    + Attributes

        + `conversions` (array, required) - A list of conversions.
            + (object)
                + `timestamp`: `"2016-02-03T03:40Z"` (string, required) - An ISO8061 formatted string representing when the conversion happened
                + `value`: 30.5 (number) - Optional conversion value in currency terms
                + `attribution` - a list of key/value pairs where the key is an AdStage id and the value is how to weight the conversion (use 1 unless you want to do multi-touch attribution modeling)
                    + `/network/adwords/campaign/530303`: 0.25 (number) - (this id is just an example, use valid ids)
                    + `/network/adwords/campaign/530304`: 0.25 (number) - (this id is just an example, use valid ids)
                    + `/network/adwords/campaign/530305`: 0.5 (number) - (this id is just an example, use valid ids)

        + `date_range`: "last 30 days" (string, required) - An AdStage date range string ("this month", "last 30 days", "2016-12-12..2016-12-15").

        + `aggregate_conversions`: true (boolean, optional)

            When true, will automatically roll up conversions into ancestor entities.
            For example, if attributing a conversion to an ad, this feature would also attribute the conversion to its ad group, campaign, and account.

            **Note that when using this feature, only the lowest level entities for each conversion should be attributed to avoid double counting.**

    + Body

            {
                "conversions": [
                    {"timestamp": "2016-11-11T06:00Z", "value": 35.0, "attribution": {"/network/adwords/campaign/143365350": 1, "/network/adwords/account/143365351": 1}},
                    {"timestamp": "2016-11-11T07:00Z", "value": 41.25, "attribution": {"/network/adwords/campaign/143365350": 0.5, "/network/adwords/campaign/143365351": 0.5}},
                    {"timestamp": "2016-11-11T07:30Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-11T08:00Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-11T08:40Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-12T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-13T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-14T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-15T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-16T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
                    {"timestamp": "2016-11-17T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}}
                ],
                "date_range": "2016-11-11..2016-11-17",
                "aggregate_conversions": true
            }

+ Response 201

## Building Reports [/v2/organizations/{org_id}/report]

Use this endpoint to pull reports at any level of reporting available within AdStage.
The V2 version of the reporting endpoint implements a full rewrite of the V1 version, providing new capabilities such as access to calculated metrics, and a much lighter weight, substantially streamlined response shape.

While this endpoint is preferred for most reporting use cases, it does not currently support reporting from external API providers, such as Facebook Direct in the Build Report V1 implementation.
Though support for data from external API providers may be introduced in the future or in a subsequent version, it is important to fully evaluate your intended development use case before selecting the V2 endpoint, the V1 endpoint, or a combination of both.

After receiving a request through the V2 reporting endpoint, AdStage will dynamically generate responses of different shapes based on the user's request.
The two main report shapes are `row` reports, which return single, metric values for each entity aggregated over the specified date range, and `series` reports, which return a time series of data points over the specified date range.
For example, AdStage uses `row` reports to return data used for displaying a pie chart of last month's spend on several campaigns, but uses a `series` report to return data used to display a line chart comparing the same campaigns' day-by-day spend.

**Because this endpoint returns results with a dynamic shape, the endpoint is split into two documentation sections.
The sections share a request schema, but document different schemas for the response shape.**

### Rows Report [POST /v2/organizations/{org_id}/report]

This type of report will return one row of metric data per requested entity with metrics aggregated across the requested timeframe.

Note however that the `results` and `summary` sections of the endpoint are independent - for example, it is possible to request `row` formatted results and a `series` formatted summary.
The Time Series Report section describes the response shapes of any components using that format.

Providing the optional `aggregate_by` key will also change the response by adding a single bulk array time series data for all metrics.
This is shaped differently than time series data in a `series` formatted request, which splits out timeseries data into one array per metric, giving just that metric's datapoints.

+ Parameters

    + `org_id` (integer) - the fetch id of the user's organization

+ Request (application/json)

    + Headers

            Accept: application/json
            Authorization: Bearer de4dxxxxb33f

    + Attributes

        + version: "2" (string, required)

            The APIs version number; currently only accepts `"2"`.

            Note that in the future, AdStage may release other minor or patch versions within the `/v2` URL namespace according to semantic versioning.

        + `date_range`: "last 30 days" (string, required)

            An AdStage date range string indicating the period to report data for.

            See the list of allowed relative or absolute date strings in the Date Ranges section.

        + `output_format`: "row", "series" (enum[string], required)

            Determines whether a report will aggregate metrics within the given date range (a `row` report), or whether the results will be given as a time series (a `series` report).

            Both formats will provide the aggregated metrics values across the full time period for each entity.
            If this is the only level of granularity you need, use a `row` format without setting an `aggregate_by` key to boost performance.

            A `row` report can optionally set the `aggregate_by` key.
            When `aggregate_by` is set for the `row` report, the report will additionally provide a time series breakdown of the metrics expressed **in a single array, containing all metric values in a single object** for each timeslice.

            A `series` report must set the `aggregate_by` key.
            When `aggregate_by` is set for the `series` report, the reported time series will be expressed **in many arrays of data points - one per metric**.

            Because the different ways of expressing time series reports are subtle, consider investigating both versions when prototyping an application to better understand which is the better fit for you.

            **Note that `series` reports require the `aggregate_by` key to be set to a non-null value, while `row` reports typically omit it.**

        + `aggregate_by`: "day", "week", "month"  (enum[string])

            Gives the size of each timeslice in the report's series; required only for `series` formatted requests.
            See the `output_format` key for more information about how using this key will change the response shape.

        + sources: (object, required) - The list of sources from which to report data; currently only "metrics" is implemented, though additional sources for blended reports may be implemented in the future.

            + metrics (object, required) - Indicates that the report should use AdStage's internal Metrics service to lookup the requested data. The Metrics service provides access to all ad network data that AdStage imports into its data warehouse. It does not provide access to real-time data stored on ad networks' own servers (consider the V1 Report API for accessing normalized real-time data).

                + targets: "/network/adstage/folder/5555", "/network/adstage/account_group/333", "/network/adwords/account/2332" (array[string]) - An optional list of AdStage Entity IDs to pull a report for, if not included all data available for the organization will be used. This can be a list of account groups, accounts, folders, campaigns, ad groups, ads, or keywords, so long as they are a coarser grouping than the `"entity_level"` specifies (e.g. if a campaign is given in this array and `"entity_level"` is set to `"ad_group"`, AdStage will report on all of the ad groups in the given campaign).

                + networks: "adwords", "amazon", "bing_ads", "facebook", "linkedin", "pinterest", "quora", "spotify", "twitter" (array[string], required) - The list of networks to report data for; must contain at least one network.

                + `entity_level`: "accounts", "campaigns", `"ad_groups"`, "ads", "keywords" (enum, required) - The entity level for which the report should return data.

        + fields: "clicks", "spend", "impressions" (array, required)

            A non-empty list of metrics or meta fields to include in the result.

            See the Discovering Metrics section (under V1) for a comprehensive list of allowed options.

        + filters (array) - A set of filters to limit the results by using AND conditions.
            + (object) - A filter object. Results are only returned if filter computes to true.
                + path: "meta/campaign_name" (string) - Any metric name; or, any meta name prefixed with "meta/". The current value for the metric field defined in the "path" key will be compared against the value given in the "value" key.

                + value: "Performance Campaigns" - A comparison number, string, or array to filter the results with, that works with the designated operator.

                + op: (enum) - The operator to compare the metric value to the "value" key's value.
                    + "gt" - greater than
                    + "lt" - less than
                    + "gte" - greater than or equal
                    + "lte" - less than or equal
                    + "in" - exact match to one of the values provided in the filter
                    + "iin" - case-insensitive match for one of the values provided in the filter
                    + "match" - case-sensitive string matching
                    + "nomatch" - case-sensitive string NOT matching
                    + "imatch" - case-insensitive string matching
                    + "inomatch" - case-insensitive string NOT matching

        + `summarize_on`: (array) - Designates the types of summaries that the report will provide, aggregating metrics across entities. When provided, the `summary_format` and `summary_fields` keys must also be provided.

            + "page"

                Aggregates metrics for all results on the resulting report's page, **ignoring results from previous or subsequent pages**.

            + "filtered"

                Aggregates metrics for all results obeying any given filters, **even if the result is not included on the current page**.

        + `summary_fields`: "clicks", "spend", (array)

            The list of fields to provide summaries for.
            Note that any field requested in `summary_fields` must also be requested under the `fields` key.
            When provided, the `summary_format` and `summarize_on` keys must also be provided.

        + `summary_format`: "row", "series" (enum)

            Determines whether a report's summary will aggregate metrics within the given date range (a `row` summary), or whether the results will be given as a time series (a `series` summary).

            Both formats will provide the aggregated metrics values across the full time period for each entity.
            If this is the only level of granularity you need, use a `row` summary without setting an `aggregate_by` key to boost performance.

            A `row` summary can optionally set the `aggregate_by` key.
            When `aggregate_by` is set for the `row` format summary, the summary will additionally provide a time series breakdown of the metrics expressed **in a single array, containing all metric values in a single object** for each timeslice.

            A `series` summary must set the `aggregate_by` key.
            When `aggregate_by` is set for the `series` format summary, the summarized time series will be expressed **in many arrays of data points - one per metric**.

            Because the different ways of expressing time series summaries are subtle, consider investigating both versions when prototyping an application to better understand which is the better fit for you.

            **Note that `series` summaries require the `aggregate_by` key to be set to a non-null value, while `row` summaries typically omit it.**

        + `sort_by`: "clicks" (string, required)

            The name of the metric or meta field to sort the results by.
            If no particular sorting is desired, consider an arbitary metric such as `spend`.

        + order: "asc", "desc" (enum)

            The direction to sort the results.
            If this key is omitted, the sort will default to descending order.

        + `group_by`: "network" (string)

            The meta field to group the results by.
            The metrics for each grouping will all be aggregated in the report results.

            Meta text fields such as campaign names will also be grouped (text will be aggregated in an array); however, the report will truncate to only the first 100 text results per group if there are over 100 entities in the group.

        + `ignore_precision`: false (boolean)

            Determines whether metrics should be rounded to their AdStage determined precision.
            Enabling this will disable automatic rounding.

        + limit: 5 (number)

            The number of rows to include (similar to SQL's `LIMIT`).
            Ignored if a page token is provided in the same request.

        + offset: 10 (number)

            The number of rows to skip before beginning the report (similar to SQL's `OFFSET`).
            Ignored if a page token is provided in the same request.

        + statuses: (enum) - Filters results based on the status codes of the reported entities

            + `all_visible` - includes only `Active`, `Paused`, and `Completed` entities (default option when the key is omitted)
            + `all_active` - includes only `Active` entities
            + `all_inactive` - includes only `Paused` and `Completed` entities
            + `all_with_deleted` - includes `Active`, `Paused`, `Completed`, `Archived`, and `Deleted` entities

        + `relative_to_datetime`: "2020-03-14" (string)
            An ISO 8601 short date or datetime string, with or without UTC offset (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, or `YYYY-MM-DDTHH:MM:SS±HH:MM`).
            When provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When omitted, requests will assume midnight of the current day.

        + `relative_to_time_zone`: "America/Los_Angeles" (string)
            A TZ Info time zone string (such as `America/Los_Angeles`).
            When provided, the request's `date_range` parameter will be set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.
            When combined with the `relative_to_datetime` parameter, that datetime will converted to its equivalent in this time zone.
            When omitted, requests will assume UTC.

        + `page_token`: "g3QAAAADZAAFbGltaXRhGWQABm9mZnNldGEAZAABdG0AAAAGb2Zmc2V0" (string)

            A Base64 encoded string describing a specific page to lookup.
            When provided, limit and offset keys will be ignored in favor of the page token.

    + Body

            {
                "version": "2",
                "date_range": "last 2 months",
                "output_format": "row",
                "aggregate_by": "month",
                "sources": {
                    "metrics": {
                        "targets": ["/network/adstage/folder/1"],
                        "networks": ["facebook", "adwords", "linkedin"],
                        "entity_level": "campaigns"
                    }
                },
                "summarize_on": ["page", "filtered"],
                "summary_fields": ["spend", "calculated_metric:123"],
                "summary_format": "row",
                "fields": ["spend", "clicks", "calculated_metric:123"],
                "filters": [
                    {
                        "op": "gt",
                        "path": "clicks",
                        "value": 5
                    }
                ],
                "sort_by": "spend",
                "order": "asc",
                "group_by": "network",
                "ignore_precision": false,
                "limit": 1,
                "offset": 1,
                "statuses": "all_visible"
            }

+ Response 200 (application/json)

    + Attributes

        + summary: (object, required) - Shows metrics aggregated across _entities_ (see the `summary_format` request key for different options on aggrgation). Value is explicit `null` if no `summary_format` was given in the request.
            + filtered (object, optional) - Shows metrics aggregated across entities on all pages for the report, subject to the constraint of given filters. Is omitted if `filtered` was not requested in the `summary_format` array.
                + calculated (object, required) - An empty object, reserved for future use.

                + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 1000`.

                + series (array, required) - Gives a single list of objects that describe all metric values for each timeslice. Omitted unless `aggregate_by` is set in the request. Note that meta values are not given in the series because they are consistent across all timeslices.
                    + (object)
                        + calculated (object, required) - An empty object, reserved for future use.

                        + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 250`.

                        + time (object, required) - Gives an object describing the span of the particular timeslice in the series data.
                            + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data for the timeslice.

                            + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data for the timeslice.

            + page: (object, optional) - Shows metrics aggrgated across all entities on the current report response page. Is omitted if `page` was not requested in the `summary_format` array. Currently omits a series even if `aggregate_by` is provided, though this may be added at a later time.
                + calculated (object, required) - Gives key-value pairs of calculated metric fields and their values, such as `"calculated_metric:123": 1000`.

                + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 50`.

            + type: (enum, required) - Gives the format of the summary.
                + `"summary_row"` - Indicates the summary section is formatted as a `row` summary.
                + `"summary_series"` - Indicates the summary section is formatted as a `series` summary.

            + summaries: "page", "filtered" (array, required) - Gives a list of each provided summary as requested in the `summarize_on` key. Options are `"page"` and `"filtered"`.

        + type: (enum, required) - Gives the type of the report so the response can be parsed based on its dynamic shape.
            + "rows" - Labels the response as that of a `row` report.
            + "timeseries" - Labels the response as that of a `series` report.

        + time (object, required) - Encapsulates information about the timespan of the report information.
            + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data.

            + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data.

            + interval: "month" (string, optional) - The timeslice interval of reported data. Only returned if the request set an `aggregate_by` parameter.

            + timestamps (array[string], optional) - An array of ISO 8601 timestamps indicating the start days of each timeslice for every reported series of data. Only returned if the request was a `series` output format.

        + `_embedded`: (object)
            + results (array) - Lists the reported data entity-by-entity (or group-by-group if `group_by` is set)
                + (object) - The reported data for one entity or grouping.
                    + calculated (object, required) - Gives key-value pairs of calculated metric fields and their values, such as `"calculated_metric:123": 1000`.

                    + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                    + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 100`.

                    + series (array, required) - Gives a single list of objects that describe all metric values for each timeslice. Omitted unless `aggregate_by` is set in the request. Note that meta values are not given in the series because they are consistent across all timeslices.
                        + (object)
                            + calculated (object, required) - Gives key-value pairs of calculated metric fields and their values, such as `"calculated_metric:123": 1000`.

                            + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 50`.

                            + time (object, required) - Gives an object describing the span of the particular timeslice in the series data.
                                + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data for the timeslice.

                                + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data for the timeslice.

                    + `_embedded` (object, required) - An empty object implementing the HAL JSON interface (reserved for future use).

                    + `_forms` (object, required) - An empty object implementing the HAL JSON interface (reserved for future use).

                    + `_links` (object, required) - A list of HAL JSON links to resources related to the reported-on entity. Currently gives a link to the entity itself: for example, a campaign will have a `adstage:network_campaign` link provided, but no links to ancestor entities.
        + `_forms`: (object) HAL JSON forms for paging through the report.
            + `next_page` (object, optional) - A HAL JSON form defining the interface and necessary JSON values for fetching the subsequent report page, if it exists.

            + `prev_page` (object, optional) - A HAL JSON form defining the interface and necessary JSON values for fetching the previous report page, if it exists.

        + `_links`: (object) - An automatically generated artifact indicating the presence of forms for paging. Does not contain HTTP body parameters; use `_forms` instead to discover the correct paging HTTP parameters.

    + Body

            {
                "summary": {
                    "filtered": {
                        "calculated": {},
                        "count": 3,
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$",
                            "entity_id": null,
                            "id": "production.1.adwords.1.accounts.adwords.123.campaigns,production.1.accounts.facebook.456.campaigns,production.1.linkedin.1.accounts.linkedin.789.campaigns",
                            "network": [
                                "linkedin",
                                "adwords",
                                "facebook"
                            ]
                        },
                        "metrics": {
                            "spend": 50973.39
                        },
                        "series": [
                            {
                                "calculated": {},
                                "metrics": {
                                    "spend": 29980.59
                                },
                                "time": {
                                    "end": "2019-05-31T23:59:59Z",
                                    "start": "2019-05-01T00:00:00Z"
                                }
                            },
                            {
                                "calculated": {},
                                "metrics": {
                                    "spend": 20992.8
                                },
                                "time": {
                                    "end": "2019-06-30T23:59:59Z",
                                    "start": "2019-06-01T00:00:00Z"
                                }
                            }
                        ]
                    },
                    "page": {
                        "calculated": {
                            "calculated_metric:123": 51591
                        },
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$"
                        },
                        "metrics": {
                            "spend": 3711.92
                        }
                    },
                    "summaries": [
                        "page",
                        "filtered"
                    ],
                    "type": "summary_row"
                },
                "type": "rows",
                "time": {
                    "end": "2019-06-30T23:59:59Z",
                    "interval": "month",
                    "start": "2019-05-01T00:00:00Z"
                },
                "_embedded": {
                    "results": [
                        {
                            "calculated": {
                                "calculated_metric:123": 51591
                            },
                            "meta": {
                                "currency_code": "USD",
                                "currency_symbol": "$",
                                "entity_id": null,
                                "id": "production.1.adwords.1.accounts.adwords.8193448926.campaigns,production.1.accounts.facebook.694893930603203.campaigns,production.1.linkedin.1.accounts.linkedin.500678349.campaigns[network=linkedin]",
                                "network": "linkedin"
                            },
                            "metrics": {
                                "clicks": 266,
                                "spend": 3711.92
                            },
                            "series": [
                                {
                                    "calculated": {
                                        "calculated_metric:123": 35259
                                    },
                                    "metrics": {
                                        "clicks": 178,
                                        "spend": 2443.85
                                    },
                                    "time": {
                                        "end": "2019-05-31T23:59:59Z",
                                        "start": "2019-05-01T00:00:00Z"
                                    }
                                },
                                {
                                    "calculated": {
                                        "calculated_metric:123": 16330
                                    },
                                    "metrics": {
                                        "clicks": 88,
                                        "spend": 1268.07
                                    },
                                    "time": {
                                        "end": "2019-06-30T23:59:59Z",
                                        "start": "2019-06-01T00:00:00Z"
                                    }
                                }
                            ],
                            "_embedded": {},
                            "_forms": {},
                            "_links": {}
                        }
                    ]
                },
                "_forms": {
                    "next_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "fields": {
                            "date_range": {
                                "type": "string",
                                "value": "last 2 months"
                            },
                            "fields": {
                                "type": "array",
                                "value": [
                                    "spend",
                                    "clicks",
                                    "calculated_metric:123"
                                ]
                            },
                            "filters": {
                                "type": "array",
                                "value": [
                                    {
                                    "op": "gt",
                                    "path": "clicks",
                                    "value": 5
                                    }
                                ]
                            },
                            "forms": {
                                "type": "array",
                                "value": null
                            },
                            "ignore_precision": {
                                "type": "boolean",
                                "value": false
                            },
                            "links": {
                                "type": [
                                    "boolean",
                                    "array"
                                ],
                                "value": null
                            },
                            "output_format": {
                                "type": "string",
                                "value": "row"
                            },
                            "sort_by": {
                                "type": "string",
                                "value": "spend"
                            },
                            "sources": {
                                "type": "object",
                                "value": {
                                    "metrics": {
                                        "targets": null,
                                        "networks": [
                                            "facebook",
                                            "adwords",
                                            "linkedin"
                                        ],
                                        "entity_level": "campaigns"
                                    }
                                }
                            },
                            "version": {
                                "type": "string",
                                "value": "2"
                            },
                            "page_token": {
                                "type": "string",
                                "value": "g3QAAAADZAAFbGltaXRhAWQABm9mZnNldGECZAABdG0AAAAGb2Zmc2V0"
                            }
                        }
                    },
                    "prev_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "fields": {
                            "date_range": {
                                "type": "string",
                                "value": "last 2 months"
                            },
                            "fields": {
                                "type": "array",
                                "value": [
                                    "spend",
                                    "clicks",
                                    "calculated_metric:123"
                                ]
                            },
                            "filters": {
                                "type": "array",
                                "value": [
                                    {
                                    "op": "gt",
                                    "path": "clicks",
                                    "value": 5
                                    }
                                ]
                            },
                            "forms": {
                                "type": "array",
                                "value": null
                            },
                            "ignore_precision": {
                                "type": "boolean",
                                "value": false
                            },
                            "links": {
                                "type": [
                                    "boolean",
                                    "array"
                                ],
                                "value": null
                            },
                            "output_format": {
                                "type": "string",
                                "value": "row"
                            },
                            "sort_by": {
                                "type": "string",
                                "value": "spend"
                            },
                            "sources": {
                                "type": "object",
                                "value": {
                                    "metrics": {
                                        "targets": null,
                                        "networks": [
                                            "facebook",
                                            "adwords",
                                            "linkedin"
                                        ],
                                        "entity_level": "campaigns"
                                    }
                                }
                            },
                            "version": {
                                "type": "string",
                                "value": "2"
                            },
                            "page_token": {
                                "type": "string",
                                "value": "g3QAAAADZAAFbGltaXRhAWQABm9mZnNldGEAZAABdG0AAAAGb2Zmc2V0"
                            }
                        }
                    }
                },
                "_links": {
                    "results": [],
                    "next_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "form": true
                    },
                    "prev_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "form": true
                    }
                }
            }

### Time Series Report [POST /v2/organizations/{org_id}/report]

This type of report will return one row of metric data per requested entity with a time series split out of that entity's metrics data.

Note however that the `results` and `summary` sections of the endpoint are independent - for example, it is possible to request `row` formatted results and a `series` formatted summary.
The Rows Report section describes the response shapes of any components using that format.

Be advised that in addition to `series` reports, `row` reports can also provide time series data, though with a different shape.
In contrast to the `series` formatted request, which splits out timeseries data into several arrays of time series (one series per metric), `row` reports are optionally able to give a single array of objects containing each metric's datapoints.

+ Parameters

    + `org_id` (integer) - the fetch id of the user's organization

+ Request (application/json)

    + Headers

            Accept: application/json
            Authorization: Bearer de4dxxxxb33f

    + Attributes

        + version: "2" (string, required)

            The APIs version number; currently only accepts `"2"`.

            Note that in the future, AdStage may release other minor or patch versions within the `/v2` URL namespace according to semantic versioning.

        + `date_range`: "last 30 days" (string, required)

            An AdStage date range string indicating the period to report data for.

            See the Date Ranges section in API Concepts.

        + `output_format`: "row", "series" (enum[string], required)

            Determines whether a report will aggregate metrics within the given date range (a `row` report), or whether the results will be given as a time series (a `series` report).

            Both formats will provide the aggregated metrics values across the full time period for each entity.
            If this is the only level of granularity you need, use a `row` format without setting an `aggregate_by` key to boost performance.

            A `row` report can optionally set the `aggregate_by` key.
            When `aggregate_by` is set for the `row` report, the report will additionally provide a time series breakdown of the metrics expressed **in a single array, containing all metric values in a single object** for each timeslice.

            A `series` report must set the `aggregate_by` key.
            When `aggregate_by` is set for the `series` report, the reported time series will be expressed **in many arrays of data points - one per metric**.

            Because the different ways of expressing time series reports are subtle, consider investigating both versions when prototyping an application to better understand which is the better fit for you.

            **Note that `series` reports require the `aggregate_by` key to be set to a non-null value, while `row` reports typically omit it.**

        + `aggregate_by`: "day", "week", "month"  (enum[string])

            Gives the size of each timeslice in the report's series; required only for `series` formatted requests.
            See the `output_format` key for more information about how using this key will change the response shape.

        + sources: (object, required) - The list of sources from which to report data; currently only "metrics" is implemented, though additional sources for blended reports may be implemented in the future.

            + metrics (object, required) - Indicates that the report should use AdStage's internal Metrics service to lookup the requested data. The Metrics service provides access to all ad network data that AdStage imports into its data warehouse. It does not provide access to real-time data stored on ad networks' own servers (consider the V1 Report API for accessing normalized real-time data).

                + targets: "/network/adstage/folder/5555", "/network/adstage/account_group/333", "/network/adwords/account/2332" (array[string]) - An optional list of AdStage Entity IDs to pull a report for, if not included all data available for the organization will be used. This can be a list of account groups, accounts, folders, campaigns, ad groups, ads, or keywords, so long as they are a coarser grouping than the `"entity_level"` specifies (e.g. if a campaign is given in this array and `"entity_level"` is set to `"ad_group"`, AdStage will report on all of the ad groups in the given campaign).

                + networks: "adwords", "amazon", "bing_ads", "facebook", "linkedin", "pinterest", "quora", "spotify", "twitter" (array[string], required) - The list of networks to report data for; must contain at least one network.

                + `entity_level`: "accounts", "campaigns", `"ad_groups"`, "ads", "keywords" (enum, required) - The entity level for which the report should return data.

        + fields: "clicks", "spend", "impressions" (array, required)

            A non-empty list of metrics or meta fields to include in the result.

            See the Discovering Metrics section (under V1) for a comprehensive list of allowed options.

        + filters (array) - A set of filters to limit the results by using AND conditions.
            + (object) - A filter object. Results are only returned if filter computes to true.
                + path: "meta/campaign_name" (string) - Any metric name; or, any meta name prefixed with "meta/". The current value for the metric field defined in the "path" key will be compared against the value given in the "value" key.

                + value: "Performance Campaigns" - A comparison number, string, or array to filter the results with, that works with the designated operator.

                + op: (enum) - The operator to compare the metric value to the "value" key's value.
                    + "gt" - greater than
                    + "lt" - less than
                    + "gte" - greater than or equal
                    + "lte" - less than or equal
                    + "in" - exact match to one of the values provided in the filter
                    + "iin" - case-insensitive match for one of the values provided in the filter
                    + "match" - case-sensitive string matching
                    + "nomatch" - case-sensitive string NOT matching
                    + "imatch" - case-insensitive string matching
                    + "inomatch" - case-insensitive string NOT matching

        + `summarize_on`: (array) - Designates the types of summaries that the report will provide, aggregating metrics across entities. When provided, the `summary_format` and `summary_fields` keys must also be provided.

            + "page"

                Aggregates metrics for all results on the resulting report's page, **ignoring results from previous or subsequent pages**.

            + "filtered"

                Aggregates metrics for all results obeying any given filters, **even if the result is not included on the current page**.

        + `summary_fields`: "clicks", "spend", (array)

            The list of fields to provide summaries for.
            Note that any field requested in `summary_fields` must also be requested under the `fields` key.
            When provided, the `summary_format` and `summarize_on` keys must also be provided.

        + `summary_format`: "row", "series" (enum)

            Determines whether a report's summary will aggregate metrics within the given date range (a `row` summary), or whether the results will be given as a time series (a `series` summary).

            Both formats will provide the aggregated metrics values across the full time period for each entity.
            If this is the only level of granularity you need, use a `row` summary without setting an `aggregate_by` key to boost performance.

            A `row` summary can optionally set the `aggregate_by` key.
            When `aggregate_by` is set for the `row` format summary, the summary will additionally provide a time series breakdown of the metrics expressed **in a single array, containing all metric values in a single object** for each timeslice.

            A `series` summary must set the `aggregate_by` key.
            When `aggregate_by` is set for the `series` format summary, the summarized time series will be expressed **in many arrays of data points - one per metric**.

            Because the different ways of expressing time series summaries are subtle, consider investigating both versions when prototyping an application to better understand which is the better fit for you.

            **Note that `series` summaries require the `aggregate_by` key to be set to a non-null value, while `row` summaries typically omit it.**

        + `sort_by`: "clicks" (string, required)

            The name of the metric or meta field to sort the results by.
            If no particular sorting is desired, consider an arbitary metric such as `spend`.

        + order: "asc", "desc" (enum)

            The direction to sort the results.
            If this key is omitted, the sort will default to descending order.

        + `group_by`: "network" (string)

            The meta field to group the results by.
            The metrics for each grouping will all be aggregated in the report results.

            Meta text fields such as campaign names will also be grouped (text will be aggregated in an array); however, the report will truncate to only the first 100 text results per group if there are over 100 entities in the group.

        + `ignore_precision`: false (boolean)

            Determines whether metrics should be rounded to their AdStage determined precision.
            Enabling this will disable automatic rounding.

        + limit: 5 (number)

            The number of rows to include (similar to SQL's `LIMIT`).
            Ignored if a page token is provided in the same request.

        + offset: 10 (number)

            The number of rows to skip before beginning the report (similar to SQL's `OFFSET`).
            Ignored if a page token is provided in the same request.

        + statuses: (enum) - Filters results based on the status codes of the reported entities

            + `all_visible` - includes only `Active`, `Paused`, and `Completed` entities (default option when the key is omitted)
            + `all_active` - includes only `Active` entities
            + `all_inactive` - includes only `Paused` and `Completed` entities
            + `all_with_deleted` - includes `Active`, `Paused`, `Completed`, `Archived`, and `Deleted` entities

        + `relative_to_datetime`: "2020-03-14" (string)
            An ISO 8601 short date or datetime string, with or without UTC offset (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, or `YYYY-MM-DDTHH:MM:SS±HH:MM`).
            When provided, the request's `date_range` parameter will be interpreted with the current moment set to this date (at midnight, if no timestamp is given).
            When omitted, requests will assume midnight of the current day.

        + `relative_to_time_zone`: "America/Los_Angeles" (string)
            A TZ Info time zone string (such as `America/Los_Angeles`).
            When provided, the request's `date_range` parameter will be set in this time zone.
            This is especially useful when used with relative `date_range` strings: for example, `today` might be January 1st in New York, but January 2nd in Sydney.
            When combined with the `relative_to_datetime` parameter, that datetime will converted to its equivalent in this time zone.
            When omitted, requests will assume UTC.

        + `page_token`: "g3QAAAADZAAFbGltaXRhGWQABm9mZnNldGEAZAABdG0AAAAGb2Zmc2V0" (string)

            A Base64 encoded string describing a specific page to lookup.
            When provided, limit and offset keys will be ignored in favor of the page token.

    + Body

            {
                "version": "2",
                "date_range": "last 2 months",
                "output_format": "series",
                "aggregate_by": "month",
                "sources": {
                        "metrics": {
                            "targets": ["/network/adstage/folder/1"],
                            "networks": ["facebook", "adwords", "linkedin"],
                            "entity_level": "campaigns"
                        }
                },
                "summarize_on": ["page", "filtered"],
                "summary_fields": ["spend", "calculated_metric:123"],
                "summary_format": "series",
                "fields": ["spend", "clicks", "calculated_metric:123"],
                "filters": [
                    {
                        "op": "gt",
                        "path": "clicks",
                        "value": 5
                    }
                ],
                "sort_by": "spend",
                "order": "asc",
                "group_by": "network",
                "ignore_precision": false,
                "limit": 1,
                "offset": 1,
                "statuses": "all_visible"
            }

+ Response 200 (application/json)

    + Attributes

        + summary: (object, required) - Shows metrics aggregated across _entities_ (see the `summary_format` request key for different options on aggrgation). Value is explicit `null` if no `summary_format` was given in the request.
            + filtered (object, optional) - Shows metrics aggregated across entities on all pages for the report, subject to the constraint of given filters. Is omitted if `filtered` was not requested in the `summary_format` array.
                + calculated (object, required) - An empty object, reserved for future use.

                + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 2000`.

                + series (object, required) - Gives a time series array of metric values for each timeslice. A separate array is provided for every metric field. Note that meta values are not given in the series because they are consistent across all timeslices.
                    + calculated (object, required) - An empty object, reserved for future use.

                    + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": [500, 1500]`.

                    + time (object, required) - Gives an object describing the span of the particular timeslice in the series data.
                        + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data for the timeslice.

                        + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data for the timeslice.

            + page: (object, optional) - Shows metrics aggrgated across all entities on the current report response page. Is omitted if `page` was not requested in the `summary_format` array. Currently omits a series even if `aggregate_by` is provided, though this may be added at a later time.
                + calculated (object, required) - Gives key-value pairs of calculated metric fields and their values, such as `"calculated_metric:123": 200`.

                + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 700`.

                + series (object, required) - Gives a time series array of metric values for each timeslice. A separate array is provided for every metric field. Note that meta values are not given in the series because they are consistent across all timeslices.
                    + calculated (object, required) - Gives key-value pairs of calculated metric fields and their time series values, such as `"calculated_metric:123": [50, 150]`.

                    + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": [200, 500]`.

                    + time (object, required) - Gives an object describing the span of the particular timeslice in the series data.
                        + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data for the timeslice.

                        + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data for the timeslice.

            + type: (enum, required) - Gives the format of the summary.
                + `"summary_row"` - Indicates the summary section is formatted as a `row` summary.
                + `"summary_series"` - Indicates the summary section is formatted as a `series` summary.

            + summaries: "page", "filtered" (array, required) - Gives a list of each provided summary as requested in the `summarize_on` key. Options are `"page"` and `"filtered"`.

        + type: (enum, required) - Gives the type of the report so the response can be parsed based on its dynamic shape.
            + "rows" - Labels the response as that of a `row` report.
            + "timeseries" - Labels the response as that of a `series` report.

        + time (object, required) - Encapsulates information about the timespan of the report information.
            + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data.

            + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data.

            + interval: "month" (string, optional) - The timeslice interval of reported data. Only returned if the request set an `aggregate_by` parameter.

            + timestamps (array[string], optional) - An array of ISO 8601 timestamps indicating the start days of each timeslice for every reported series of data. Only returned if the request was a `series` output format.

        + `_embedded`: (object)
            + results (array) - Lists the reported data entity-by-entity (or group-by-group if `group_by` is set)
                + (object) - The reported data for one entity or grouping.
                    + calculated (object, required) - Gives key-value pairs of calculated metric fields and their values, such as `"calculated_metric:123": 1000`.

                    + meta (object, required) - Gives key-value pairs of meta fields and their values, such as `"currency_code": "USD"`.

                    + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": 100`.

                    + series (object, required) - Gives a time series array of metric values for each timeslice. A separate array is provided for every metric field. Note that meta values are not given in the series because they are consistent across all timeslices.
                        + calculated (object, required) - Gives key-value pairs of calculated metric fields and their time series values, such as `"calculated_metric:123": [50, 150]`.

                        + metrics (object, required) - Gives key-value pairs of metric fields and their values, such as `"spend": [200, 500]`.

                        + time (object, required) - Gives an object describing the span of the particular timeslice in the series data.
                            + start: "2019-05-01T00:00:00Z" (string, required) - An ISO 8601 timestamp indicating the first day of the reported data for the timeslice.

                            + end: "2019-06-30T23:59:59Z" (string, required) - An ISO 8601 timestamp indicating the final day of the reported data for the timeslice.

                    + `_embedded` (object, required) - An empty object implementing the HAL JSON interface (reserved for future use).

                    + `_forms` (object, required) - An empty object implementing the HAL JSON interface (reserved for future use).

                    + `_links` (object, required) - A list of HAL JSON links to resources related to the reported-on entity. Currently gives a link to the entity itself: for example, a campaign will have a `adstage:network_campaign` link provided, but no links to ancestor entities.
        + `_forms`: (object) HAL JSON forms for paging through the report.
            + `next_page` (object, optional) - A HAL JSON form defining the interface and necessary JSON values for fetching the subsequent report page, if it exists.

            + `prev_page` (object, optional) - A HAL JSON form defining the interface and necessary JSON values for fetching the previous report page, if it exists.

        + `_links`: (object) - An automatically generated artifact indicating the presence of forms for paging. Does not contain HTTP body parameters; use `_forms` instead to discover the correct paging HTTP parameters.

    + Body

            {
                "summary": {
                    "filtered": {
                        "calculated": {},
                        "count": 3,
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$",
                            "entity_id": null,
                            "network": [
                                "linkedin",
                                "adwords",
                                "facebook"
                            ]
                        },
                        "metrics": {
                            "spend": 50973.39
                        },
                        "series": {
                            "calculated": {},
                            "metrics": {
                                "spend": [
                                    29980.59,
                                    20992.8
                                ]
                            }
                        }
                    },
                    "page": {
                        "calculated": {
                            "calculated_metric:123": 51591
                        },
                        "meta": {
                            "currency_code": "USD",
                            "currency_symbol": "$"
                        },
                        "metrics": {
                            "spend": 3711.92
                        },
                        "series": {
                            "calculated": {
                                "calculated_metric:123": [
                                    35259,
                                    16330
                                ]
                            },
                            "metrics": {
                                "spend": [
                                    2443.85,
                                    1268.07
                                ]
                            }
                        }
                    },
                    "summaries": [
                        "page",
                        "filtered"
                    ],
                    "type": "summary_series"
                },
                "type": "timeseries",
                "time": {
                    "end": "2019-06-30T23:59:59Z",
                    "interval": "month",
                    "start": "2019-05-01T00:00:00Z",
                    "timestamps": [
                        "2019-05-01T00:00:00Z",
                        "2019-06-01T00:00:00Z"
                    ]
                },
                "_embedded": {
                    "results": [
                        {
                            "summary": {
                                "calculated": {
                                    "calculated_metric:123": 51591
                                },
                                "meta": {
                                    "currency_code": "USD",
                                    "currency_symbol": "$",
                                    "entity_id": null,
                                    "network": "linkedin"
                                },
                                "metrics": {
                                    "clicks": 266,
                                    "spend": 3711.92
                                }
                            },
                            "series": {
                                "calculated": {
                                    "calculated_metric:123": [
                                        35259,
                                        16330
                                    ]
                                },
                                "metrics": {
                                    "clicks": [
                                        178,
                                        88
                                    ],
                                    "spend": [
                                        2443.85,
                                        1268.07
                                    ]
                                }
                            },
                            "_embedded": {},
                            "_forms": {},
                            "_links": {}
                        }
                    ]
                },
                "_forms": {
                    "next_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "fields": {
                            "date_range": {
                                "type": "string",
                                "value": "last 2 months"
                            },
                            "fields": {
                                "type": "array",
                                "value": [
                                    "spend",
                                    "clicks",
                                    "calculated_metric:123"
                                ]
                            },
                            "filters": {
                                "type": "array",
                                "value": [
                                    {
                                        "op": "gt",
                                        "path": "clicks",
                                        "value": 5
                                    }
                                ]
                            },
                            "forms": {
                                "type": "array",
                                "value": null
                            },
                            "ignore_precision": {
                                "type": "boolean",
                                "value": false
                            },
                            "links": {
                                "type": [
                                    "boolean",
                                    "array"
                                ],
                                "value": null
                            },
                            "output_format": {
                                "type": "string",
                                "value": "series"
                            },
                            "sort_by": {
                                "type": "string",
                                "value": "spend"
                            },
                            "sources": {
                                "type": "object",
                                "value": {
                                    "metrics": {
                                        "targets": [
                                            "/network/adstage/organization/1"
                                        ],
                                        "networks": [
                                            "facebook",
                                            "adwords",
                                            "linkedin"
                                        ],
                                        "entity_level": "campaigns"
                                    }
                                }
                            },
                            "version": {
                                "type": "string",
                                "value": "2"
                            },
                            "page_token": {
                                "type": "string",
                                "value": "g3QAAAADZAAFbGltaXRhAWQABm9mZnNldGECZAABdG0AAAAGb2Zmc2V0"
                            }
                        }
                    },
                    "prev_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "fields": {
                            "date_range": {
                                "type": "string",
                                "value": "last 2 months"
                            },
                            "fields": {
                                "type": "array",
                                "value": [
                                    "spend",
                                    "clicks",
                                    "calculated_metric:123"
                                ]
                            },
                            "filters": {
                                "type": "array",
                                "value": [
                                    {
                                        "op": "gt",
                                        "path": "clicks",
                                        "value": 5
                                    }
                                ]
                            },
                            "forms": {
                                "type": "array",
                                "value": null
                            },
                            "ignore_precision": {
                                "type": "boolean",
                                "value": false
                            },
                            "links": {
                                "type": [
                                    "boolean",
                                    "array"
                                ],
                                "value": null
                            },
                            "output_format": {
                                "type": "string",
                                "value": "series"
                            },
                            "sort_by": {
                                "type": "string",
                                "value": "spend"
                            },
                            "sources": {
                                "type": "object",
                                "value": {
                                    "metrics": {
                                        "targets": [
                                            "/network/adstage/organization/1"
                                        ],
                                        "networks": [
                                            "facebook",
                                            "adwords",
                                            "linkedin"
                                        ],
                                        "entity_level": "campaigns"
                                    }
                                }
                            },
                            "version": {
                                "type": "string",
                                "value": "2"
                            },
                            "page_token": {
                                "type": "string",
                                "value": "g3QAAAADZAAFbGltaXRhAWQABm9mZnNldGEAZAABdG0AAAAGb2Zmc2V0"
                            }
                        }
                    }
                },
                "_links": {
                    "results": [],
                    "next_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "form": true
                    },
                    "prev_page": {
                        "href": "https://platform.adstage.io/api/organizations/1/report",
                        "method": "POST",
                        "form": true
                    }
                }
            }