> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/engagement-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/engagement-api/querying-data/appearance-queries.md).

# Appearance Queries

### Types of Appearance Queries

Appearance Queries can further be divided into two categories:

* Channel Appearances (Require lookup by [company hash](/engagement-api/querying-data/introduction.md#what-is-a-company-hash))
* Content Appearances (Require lookup by content ID)

### Channel Appearances

Channel Appearances identify how the company **and related content** were accessed on a particular channel (such as `Website`, `Print` and `Newsletter`). Channel Appearances are queried using the [company hash](/engagement-api/querying-data/introduction.md#what-is-a-company-hash) and a date range using the format of `{ start: "YYYY-MM", end: "YYYY-MM" }`. It will return the following data for each:

#### Website Channel Appearances

Includes content metadata and website metrics -- notably the following:

* Views: The number of times the company was viewed, including the profile page and related content.
* Users : The total number of users that viewed the company (and related content).
* Rows: A breakout of the above data by each distinct content item.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
query { 
  websiteAppearances(input: {
    companyHash: "COMPANY_HASH_GOES_HERE",
    monthRange: { start: "2022-01", end: "2022-12" }
  }) { 
    views
    users
    rows { 
      views 
      uniqueUsers
      content {
        id
        name
        type 
        published 
        primarySite { 
          id
          name
          title
          shortName
          host
        } 
      } 
    } 
  } 
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "websiteAppearances": {
      "views": 323,
      "users": 235,
      "rows": [
        {
          "views": 64,
          "uniqueUsers": 54,
          "content": {
            "id": 22131807,
            "name": "Content name",
            "type": "Product",
            "published": "2022-03-24T14:59:31.000Z",
            "primarySite": {
              "id": "5f179a9900d6f47b4c98ddec",
              "name": "Website Name",
              "title": "Website Name (WSN)",
              "shortName": "WSN",
              "host": "www.website.com"
            }
          }
        }
        // ...
      ]
    }
  }
}
```

{% endcode %}

</details>

#### Print Channel Appearances

Includes content and print issue metadata.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
  printAppearances(input: {
    companyHash: "585a7978a7bc179300e6b483a107753c",
    monthRange: { start: "2022-01", end: "2022-12" }
  }) {
    content {
      id
      type
      published
    }
    issues {
      id
      name
      mailed
      publication {
        id
        name
      }		
    }
  }
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "printAppearances": [
      {
        "content": {
          "id": 22485616,
          "type": "Article",
          "published": "2022-10-11T16:57:51.000Z"
        },
        "issues": [
          {
            "id": 49945,
            "name": "September/October 2022",
            "mailed": "2022-09-28T05:00:00.000Z",
            "publication": {
              "id": "5f3191b79ad4092e008b4574",
              "name": "Example Publication"
            }
          }
        ]
      }
    ],
  }
}
```

{% endcode %}

</details>

#### Newsletter Channel appearances

Includes content and newsletter deployment metadata.

<details>

<summary>Example query</summary>

{% code title="" %}

```graphql
// Some code
```

{% endcode %}

{% code title="" %}

```json
// Some code
```

{% endcode %}

</details>

## Content Appearances

Content Appearances identify where the individual content item appeared in the channel. Like Channel Appearances, this query identifies where the content item appeared within a channel, and supports a date range using the same format as above.

#### Content Website Appearances

The `contentWebsiteAppearances` query returns website section metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
query {
  contentWebsiteAppearances(input: {
    contentId: 12345678
    monthRange: { start: "2022-01", end: "2022-12" }
  }) {
    content {
      id
      type
      published
    }
    sections {
      id
     name
    }
  }
}
```

{% endcode %}

{% code title="JSON Response" %}

```json
{
  "data": {
    "contentWebsiteAppearances": {
      "content": {
        "id": 12345678,
        "type": "Article",
        "published": "2020-09-02T21:58:24.000Z"
      },
      "sections": [
        {
          "id": 64202,
          "name": "Products"
        }
      ]
    }
  }
}
```

{% endcode %}

</details>

#### Content Print Appearances

The `contentPrintAppearances` query returns magazine issue metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="" %}

```graphql
// Some code
```

{% endcode %}

{% code title="" %}

```json
// Some code
```

{% endcode %}

</details>

#### Content Newsletter Appearances

The `contentNewsletterAppearances` query returns newsletter deployment metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
newsletterAppearances(input: {
  companyHash: "585a7978a7bc179300e6b483a107753c",
  monthRange: { start: "2022-01", end: "2022-12" }
}) {
  content {
    id
    type
    published
  }
  deployments {
    id
    day
    newsletter {
      id
      name
    }
  }
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "newsletterAppearances": [
      {
        "content": {
          "id": 22485616,
          "type": "Article",
          "published": "2022-10-11T16:57:51.000Z"
        },
        "deployments": [
          {
            "id": "5f20800300d6f47b4c0c58d9.2022-10-12",
            "day": "2022-10-12",
            "newsletter": {
              "id": "5f20800300d6f47b4c0c58d9",
              "name": "Newsletter"
            }
          }
        ]
      },
      {
        "content": {
          "id": 22131807,
          "type": "Product",
          "published": "2022-03-24T14:59:31.000Z"
        },
        "deployments": [
          {
            "id": "5f20800300d6f47b4c0c58d9.2022-03-30",
            "day": "2022-03-30",
            "newsletter": {
              "id": "5f20800300d6f47b4c0c58d9",
              "name": "Newsletter"
            }
          },
          {
            "id": "5f4014f90b2c96a3058b459b.2022-03-24",
            "day": "2022-03-24",
            "newsletter": {
              "id": "5f4014f90b2c96a3058b459b",
              "name": "Product Roundup"
            }
          }
        ]
      }
    ]
  }
}
```

{% endcode %}

</details>