> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/native-x-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parameter1.com/native-x-api/querying-data/queries.md).

# Queries

The bulk of queries to the Native-X API can be divided into the following three categories:

* Singular Data Queries
* Plural Data Queries
* Metric Data Queries

To provide as high level of an overview of how to use these queries we're going to focus on the following queries for each respective category:

* `publisher` (Singular Data Queries)
* `allPublishers` (Plural Data Queries)
* `dailyCampaignMetrics` and `publisherMetricBreakouts` (Metric Data Queries)

### Singular Data Queries

To understand how to perform a singular data query, let's take a look at the `publisher` query. Here is an example:

{% hint style="info" %}
The following example only includes of subset of all the possible fields that can be returned via this query, for a more thorough overview of the available fields and what data they contain please consult [An Outline of Types ](/native-x-api/querying-data/an-outline-of-types.md)more specifically the [Publisher](/native-x-api/querying-data/an-outline-of-types.md#publisher) type.
{% endhint %}

{% tabs %}
{% tab title="Query" %}

```javascript
query publisher($input: ModelIdInput!, $startDate: Date!, $endDate: Date!) {
  publisher(input: $input) {
    id
    name
    website
    logo {
      src
    }

    topics {
      totalCount
      edges {
        node {
          id
          name
          placements {
            edges {
              node {
                id
                name
                
                metrics (start: $startDate, end: $endDate) {
                  ctr
                  clicks
                  views
                }
                
              }
            }
          }
        }
      }
    }

    campaigns(pagination: { first: 1 }) {
      totalCount
      edges {
        node {
          id
          name
          hash
          
          advertiser {
            id
            name
            externalId
          }
          
          creatives {
            id
            title
          }
          
          criteria {
            start
            end
          }
          
          metrics {
            ctr
            views
            clicks
          }
          
          reports {
            byDay(startDate: $startDate, endDate: $endDate){
              day(format: "MMMM D YYYY")
              metrics {
                ctr
                views
                clicks
              }
            }
          }
          
        }
      }
    }

    emailDeployments {
      totalCount
      edges {
        node {
          id
          name
        }
      }
    }

    metrics(start: $startDate, end: $endDate ) {
      ctr
      views
      clicks
    }

  }
}
```

{% endtab %}

{% tab title="Variables" %}

```json
{
  "input" :{
    "id": "4f44444e4a44aa4444dbcfd4"
  },
  "startDate": 1664427600000,
  "endDate": 1667322969625
}
```

{% endtab %}

{% tab title="Headers" %}

```json
{
  "Authorization": "Bearer AUTH_TOKEN_GOES_HERE"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "publisher": {
      "id": "4f44444e4a44aa4444dbcfd4",
      "name": "Native-X Test Publication",
      "website": "https://www.parameter1.com",
      "logo": {
        "src": "https://native-x.imgix.net/p1/4f4444a444e4a44444444ae4/logo.png"
      },
      
      "topics": {
        "totalCount": 2,
        "edges": [
          {
            "node": {
              "id": "4fee2f23eb02340001e7d653",
              "name": "Example Topic 1",
              "placements": {
                "edges": []
              }
            }
          },
          {
            "node": {
              "id": "4feca4fa6bbf2e0002b050e3",
              "name": "Example Topic 2",
              "placements": {
                "edges": [
                  {
                    "node": {
                      "id": "4ff56b19eb02160001fb39db",
                      "name": "Example Placement 1",
                      "metrics": {
                        "ctr": 0.5,
                        "clicks": 2,
                        "views": 4
                      }
                    }
                  },
                  {
                    "node": {
                      "id": "4fee4ba04bbf4e0001b74347",
                      "name": "Example Placement 2",
                      "metrics": {
                        "ctr": 0.05,
                        "clicks": 50,
                        "views": 1000
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      
      "campaigns": {
        "totalCount": 29,
        "edges": [
          {
            "node": {
              "id": "4557e9350375a10003341b8c",
              "name": "Example Campaign 1",
              "hash": "-MW8CrWWrqrUcdGsV_Hi",
              
              "advertiser": {
                "id": "403211e31e27d4000950050a",
                "name": "Top Shelf Products",
                "externalId": "69501"
              },
              
              "creatives": [
                {
                  "id": "6335e7708153a9000112a6ec",
                  "title": "Top Shelf Products, second to none"
                }
              ],
              
              "criteria": {
                "start": 1664427600000,
                "end": 1669874399999
              },
              
              "metrics": {
                "ctr": 0.002464279790536218,
                "views": 42203,
                "clicks": 104
              },
              
              "reports": {
                "byDay": [
                  {
                    "day": "September 29 2022",
                    "metrics": {
                      "ctr": 0,
                      "views": 591,
                      "clicks": 0
                    }
                  },
                  {
                    "day": "September 30 2022",
                    "metrics": {
                      "ctr": 0.0035087719298245615,
                      "views": 1140,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 1 2022",
                    "metrics": {
                      "ctr": 0.0018264840182648401,
                      "views": 1095,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 2 2022",
                    "metrics": {
                      "ctr": 0.0010121457489878543,
                      "views": 988,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "October 3 2022",
                    "metrics": {
                      "ctr": 0.0016420361247947454,
                      "views": 1218,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 4 2022",
                    "metrics": {
                      "ctr": 0,
                      "views": 1263,
                      "clicks": 0
                    }
                  },
                  {
                    "day": "October 5 2022",
                    "metrics": {
                      "ctr": 0.004629629629629629,
                      "views": 1296,
                      "clicks": 6
                    }
                  },
                  {
                    "day": "October 6 2022",
                    "metrics": {
                      "ctr": 0.003000750187546887,
                      "views": 1333,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 7 2022",
                    "metrics": {
                      "ctr": 0.0037914691943127963,
                      "views": 1055,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 8 2022",
                    "metrics": {
                      "ctr": 0.0011299435028248588,
                      "views": 885,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "October 9 2022",
                    "metrics": {
                      "ctr": 0.0022346368715083797,
                      "views": 895,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 10 2022",
                    "metrics": {
                      "ctr": 0.0029563932002956393,
                      "views": 1353,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 11 2022",
                    "metrics": {
                      "ctr": 0.002364066193853428,
                      "views": 1269,
                      "clicks": 3
                    }
                  },
                  {
                    "day": "October 12 2022",
                    "metrics": {
                      "ctr": 0.0007412898443291327,
                      "views": 1349,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "October 13 2022",
                    "metrics": {
                      "ctr": 0.0006693440428380187,
                      "views": 1494,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "October 14 2022",
                    "metrics": {
                      "ctr": 0.0007739938080495357,
                      "views": 1292,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "October 15 2022",
                    "metrics": {
                      "ctr": 0,
                      "views": 1059,
                      "clicks": 0
                    }
                  },
                  {
                    "day": "October 16 2022",
                    "metrics": {
                      "ctr": 0.0020491803278688526,
                      "views": 976,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 17 2022",
                    "metrics": {
                      "ctr": 0.0013504388926401081,
                      "views": 1481,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 18 2022",
                    "metrics": {
                      "ctr": 0.002600780234070221,
                      "views": 1538,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 19 2022",
                    "metrics": {
                      "ctr": 0.0019880715705765406,
                      "views": 1509,
                      "clicks": 3
                    }
                  },
                  {
                    "day": "October 20 2022",
                    "metrics": {
                      "ctr": 0.002544529262086514,
                      "views": 1572,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 21 2022",
                    "metrics": {
                      "ctr": 0.005372733378106112,
                      "views": 1489,
                      "clicks": 8
                    }
                  },
                  {
                    "day": "October 22 2022",
                    "metrics": {
                      "ctr": 0.006741573033707865,
                      "views": 890,
                      "clicks": 6
                    }
                  },
                  {
                    "day": "October 23 2022",
                    "metrics": {
                      "ctr": 0.004640371229698376,
                      "views": 862,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 24 2022",
                    "metrics": {
                      "ctr": 0.00501002004008016,
                      "views": 1996,
                      "clicks": 10
                    }
                  },
                  {
                    "day": "October 25 2022",
                    "metrics": {
                      "ctr": 0.00133422281521014,
                      "views": 1499,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 26 2022",
                    "metrics": {
                      "ctr": 0.0012515644555694619,
                      "views": 1598,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 27 2022",
                    "metrics": {
                      "ctr": 0.004931506849315068,
                      "views": 1825,
                      "clicks": 9
                    }
                  },
                  {
                    "day": "October 28 2022",
                    "metrics": {
                      "ctr": 0.0025380710659898475,
                      "views": 1576,
                      "clicks": 4
                    }
                  },
                  {
                    "day": "October 29 2022",
                    "metrics": {
                      "ctr": 0.0019305019305019305,
                      "views": 1036,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 30 2022",
                    "metrics": {
                      "ctr": 0.0020387359836901123,
                      "views": 981,
                      "clicks": 2
                    }
                  },
                  {
                    "day": "October 31 2022",
                    "metrics": {
                      "ctr": 0.0008710801393728223,
                      "views": 1148,
                      "clicks": 1
                    }
                  },
                  {
                    "day": "November 1 2022",
                    "metrics": {
                      "ctr": 0.004601226993865031,
                      "views": 652,
                      "clicks": 3
                    }
                  }
                ]
              }
              
            }
          }
        ]
      },
      
      "emailDeployments": {
        "totalCount": 1,
        "edges": [
          {
            "node": {
              "id": "4070b3ff71bd30000124e455",
              "name": "The Newsletter"
            }
          }
        ]
      },
      
      "metrics": {
        "ctr": 0.004232596761544494,
        "views": 86708,
        "clicks": 367
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

Lets take a more condensed look at this working with just `Campaigns` for a given `Publisher`:

{% hint style="info" %}
Note: This query makes an assumption to paginate to a subsequent "page" after retrieving an initial set of results with the return of `Campaigns.pageInfo.endCursor` for use in a `previousCursor` variable.
{% endhint %}

{% tabs %}
{% tab title="Query" %}

```javascript
query publisher($input: ModelIdInput!, $startDate:Date!, $endDate: Date!, $previousCursor: Cursor!) {
  publisher(input: $input) {
    id
    name
    campaigns(pagination: {first: 5, after: $previousCursor}) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          name
          hash
          
          advertiser {
            id
            name
            externalId
          }
          
          creatives {
            id
            title
          }
          
          criteria {
            start
            end
          }
          
          metrics {
            ctr
            views
            clicks
          }
          
          reports {
            byDay(startDate: $startDate, endDate: $endDate){
              day(format: "MMMM D YYYY")
              metrics {
                ctr
                views
                clicks
              }
            }
          }
          
        }
      }
    }
  }
}
```

{% endtab %}

{% tab title="Variables" %}

```json
{
  "input" :{
    "id":"4f44444e4a44aa4444dbcfd4"
  },
  "startDate": 1598504400000,
  "endDate": 1598604400000,
  "previousCursor": "NWY0N2YwOGZlMDAyZjYwMDAxMTc1NDhh"
}
```

{% endtab %}

{% tab title="Header" %}

```json
{
  "Authorization": "Bearer AUTH_TOKEN_GOES_HERE"
}
```

{% endtab %}

{% tab title="Response" %}

```
{
  "data": {
    "publisher": {
      "id": "4f44444e4a44aa4444dbcfd4",
      "name": "Native-X Test Publication",
      "campaigns": {
        "totalCount": 29,
        "pageInfo": {
          "hasNextPage": false,
          "endCursor": "NWY0MDQ4ODA1OGUyYTIwMDAxNzkxYzhm"
        },
        "edges": [
          {
            "node": {
              "id": "3f69ed00ed7a140001a356ed",
              "name": "A Very Hip Advertising Campaign",
              "hash": "-WPxkS99TE45ps3d2d12",
              "advertiser": {
                "id": "5f6e53f9c97e200001d94e68",
                "name": "An Advertising Agency",
                "externalId": "45451"
              },
              "creatives": [
                {
                  "id": "3f25ee21609c11000975ea31",
                  "title": "A Very Hip Advertising Creative",
                }
              ],
              "criteria": {
                "start": 1598504400000,
                "end": 1601528399999
              },
              "metrics": {
                "ctr": 0.00378698224852071,
                "views": 12675,
                "clicks": 48
              },
              "reports": {
                "byDay": [
                  {
                    "day": "August 27 2020",
                    "metrics": {
                      "ctr": 0,
                      "views": 192,
                      "clicks": 0
                    }
                  },
                  {
                    "day": "August 28 2020",
                    "metrics": {
                      "ctr": 0.007731958762886598,
                      "views": 388,
                      "clicks": 3
                    }
                  }
                ]
              }
            }
          },
          {
            "node": {
              "id": "3f24b3e9e94a2100099a0e5d",
              "name": "Native-X Advertising Campaign",
              "hash": "-TFgDee7ZrAgCi8K-bz",
              "advertiser": {
                "id": "3f4e3534c79e000009da0064",
                "name": "Native-X Advertisting Incorporated",
                "externalId": "99995"
              },
              "creatives": [
                {
                  "id": "3f24b446e000f400099270a9",
                  "title": "The Native-X Advertisement",
                }
              ],
              "criteria": {
                "start": 1598418000000,
                "end": 1601528399999
              },
              "metrics": {
                "ctr": 0.002353834472285497,
                "views": 13170,
                "clicks": 31
              },
              "reports": {
                "byDay": [
                  {
                    "day": "August 27 2020",
                    "metrics": {
                      "ctr": 0.01282051282051282,
                      "views": 468,
                      "clicks": 6
                    }
                  },
                  {
                    "day": "August 28 2020",
                    "metrics": {
                      "ctr": 0,
                      "views": 417,
                      "clicks": 0
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
```

{% endtab %}
{% endtabs %}

This example query could be done perpetually until there are no longer any Campaigns query for. By default the `first` value for the `pagination` input is 25 so in the event you have a `totalCount` less than that for any query pagination becomes unnecessary. This will typically be indicated by `pageInfo.hasNextPage` being set to `false`.

### Plural Data Queries

To understand how to perform a plural data query, let's take a look at the `allPublishers` query. Here is an example:

{% hint style="info" %}
Note: The following example is condensed to demonstrate the nature of a "plural" query the overall field definitions are the same as their singular counterpart, with the addition of a wrapping `Connection` for more information on `Connection` and other data types please consult [An Outline of Types ](/native-x-api/querying-data/an-outline-of-types.md)and more particularly [What is a connection?](/native-x-api/querying-data/an-outline-of-types.md#what-is-a-connection) for information regarding the `Connection` schema type.
{% endhint %}

{% tabs %}
{% tab title="Query" %}

```javascript
query {
  allPublishers {
    totalCount
    edges {
      node {
        id
        name
      }
    }
  }
}
```

{% endtab %}

{% tab title="Headers" %}

```json
{
  "Authorization": "Bearer AUTH_TOKEN_GOES_HERE"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "allPublishers": {
      "totalCount": 4,
      "edges": [
        {
          "node": {
            "id": "3f20300ec5f07000016afc10",
            "name": "Generic Publisher"
          }
        },
        {
          "node": {
            "id": "3f202ff5c5f07000096afbea",
            "name": "Not So Generic Publisher"
          }
        },
        {
          "node": {
            "id": "3f202f71c5f07000096afbc3",
            "name": "Extremely Awesome Publisher"
          }
        },
        {
          "node": {
            "id": "3f202f41c5f07000016afba0",
            "name": "Publisher of Things"
          }
        }
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Metric Data Queries

Lastly we'll quickly cover a couple examples of Metric Data Queries using `dailyCampaignMetrics` and `publisherMetricBreakouts`

{% tabs %}
{% tab title="Query" %}

```javascript
query dailyCampaignMetrics($day: Date!) {
  dailyCampaignMetrics(day: $day) {
    campaigns
    views
    clicks
    ctr
  }
}
```

{% endtab %}

{% tab title="Variables" %}

```json
{
  "day": 1598504400000
}
```

{% endtab %}

{% tab title="Headers" %}

```json
{
  "Authorization": "Bearer AUTH_TOKEN_GOES_HERE"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "dailyCampaignMetrics": {
      "campaigns": 39,
      "views": 3271,
      "clicks": 26,
      "ctr": 0.007948639559767655
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Query" %}

```javascript
query publisherMetricBreakouts($input: BreakoutMetricsInput!, $sort:PublisherMetricsSortInput){
publisherMetricBreakouts(input:$input, sort:$sort) {
    publisherName
    views
    clicks
    ctr
  }
}
```

{% endtab %}

{% tab title="Variables" %}

```json
{
  "input": {
    "startDay": 1598504400000,
    "endDay": 1598604400000
  },
  "sort": {
    "field": "clicks",
    "order": 1
  }
}
```

{% endtab %}

{% tab title="Headers" %}

```json
{
  "Authorization": "Bearer AUTH_TOKEN_GOES_HERE"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "publisherMetricBreakouts": [
      {
        "publisherName": "Native-X Publishing Alpha",
        "views": 0,
        "clicks": 0,
        "ctr": 0
      },
      {
        "publisherName": "Native-X Publishing Beta",
        "views": 0,
        "clicks": 0,
        "ctr": 0
      },
      {
        "publisherName": "Native-X Publishing Gamma",
        "views": 0,
        "clicks": 0,
        "ctr": 0
      },
      {
        "publisherName": "Native-X Publishing Delta",
        "views": 0,
        "clicks": 0,
        "ctr": 0
      },
      {
        "publisherName": "Native-X Publishing Epsilon",
        "views": 4594,
        "clicks": 16,
        "ctr": 0.0034828036569438396
      },
      {
        "publisherName": "Native-X Publishing Kappa",
        "views": 5119,
        "clicks": 41,
        "ctr": 0.008009376831412385
      },
      {
        "publisherName": "Native-X Publishing Alef",
        "views": 5046,
        "clicks": 42,
        "ctr": 0.008323424494649227
      },
      {
        "publisherName": "Native-X Publishing Omega",
        "views": 6636,
        "clicks": 46,
        "ctr": 0.006931886678722122
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}