### Get Landscape Companies Endpoint (Curl Example)

Source: https://app.rivaliq.com/api-reference/index

This snippet provides an example of how to call the 'Get landscape companies' endpoint using curl. It demonstrates the basic structure of the request, including the endpoint URL and necessary permissions.

```bash
curl

```

--------------------------------

### API Success Response Example (202 Accepted)

Source: https://app.rivaliq.com/api-reference/index

Example of a successful API response, typically returning a bulk download token upon initiating a data retrieval request.

```json
{
  "token": "gAaBbCcDdEeF"
}
```

--------------------------------

### GET /Landscape/Available

Source: https://app.rivaliq.com/api-reference/index

Retrieves a list of all available landscapes within the Rival IQ platform.

```APIDOC
## GET /Landscape/Available

### Description
Get a list of available landscapes.

### Method
GET

### Endpoint
/landscape/available

### Parameters
#### Query Parameters
- **apiKey** (String) - Required - The user's unique API key
- **v** (String) - Optional - Cache buster (value ignored). This parameter has no effect on the data retrieved or the response generated by the Rival IQ server. This can be used to ensure intermediate layers (proxies, etc) pass the request through rather than return previously cached responses.

### Response
#### Success Response (200)
(Response structure not detailed in the provided text, but typically would be a JSON array of landscape objects.)

#### Response Example
(Example response not provided in the source text.)
```

--------------------------------

### API Success Response Example (JSON)

Source: https://app.rivaliq.com/api-reference/index

An example of a successful API response in JSON format, containing various metrics for a company across different platforms.

```json
{
  "metrics": [
    {
      "companyName": "Seattle Seahawks",
      "companyId": 6909,
      "mainPeriodStart": "2022-11-01T00:00:00.000Z",
      "mainPeriodEnd": "2022-11-15T23:59:59.999Z",
      "comparePeriodStart": "2022-10-17T00:00:00.000Z",
      "comparePeriodEnd": "2022-10-31T23:59:59.999Z",
      "twitterAllTweets": 276,
      "twitterAverageOfAllTweetsPerDay": 18.4,
      "twitterRetweets": 28370,
      "twitterAverageRetweetsPerDay": 1891.3333333333333,
      "twitterLikesOfCompanyTweets": 288831,
      "twitterAverageLikesPerDay": 19255.4,
      "twitterTweetEngagementTotal": 323092,
      "twitterAverageEngagementTotalPerDay": 21539.466666666667,
      "twitterAverageEngagementTotalPerTweet": 1591.5862068965516,
      "twitterAverageEngagementRatePerTweet": 0.000619851880126273,
      "twitterLifetimeTweets": 87691,
      "twitterTweets": 203,
      "twitterAverageTweetsPerDay": 13.533333333333333,
      "twitterRetweetTweets": 48,
      "twitterAverageRetweetTweetsPerDay": 3.2,
      "twitterReplyTweets": 25,
      "twitterAverageReplyTweetsPerDay": 1.6666666666666667,
      "twitterFollowerToFollowingRatio": 2726.837,
      "twitterRepliesToCompanyTweets": 5891,
      "twitterAverageRepliesPerDay": 392.73333333333335,
      "twitterVideoViews": 5617642,
      "twitterAverageVideoViewsPerDay": 374509.4666666667,
      "twitterEstimatedImpressions": 15703012,
      "twitterEngagementRateByEstimatedImpression": 0.020575160994591356,
      "twitterImpressions": 15703012,
      "youTubeSubscribers": 191000,
      "youTubeVideos": 4393,
      "youTubeLifetimeViews": 52044844,
      "youTubeComments": null,
      "youTubePosts": 86,
      "youTubeAveragePostsPerDay": 5.733333333333333,
      "youTubePostViews": 1623723,
      "youTubeAveragePostViewsPerDay": 108248.2,
      "youTubePostLikes": 52716
    }
  ]
}
```

--------------------------------

### API Success Response Example (CSV)

Source: https://app.rivaliq.com/api-reference/index

An example of a successful API response in CSV format, presenting company metrics in a tabular structure.

```csv
"companyName","companyId","mainPeriodStart","mainPeriodEnd","comparePeriodStart","comparePeriodEnd","twitterAllTweets","twitterAverageOfAllTweetsPerDay","twitterRetweets","twitterAverageRetweetsPerDay","twitterLikesOfCompanyTweets","twitterAverageLikesPerDay","twitterTweetEngagementTotal","twitterAverageEngagementTotalPerDay","twitterAverageEngagementTotalPerTweet","twitterAverageEngagementRatePerTweet","twitterLifetimeTweets","twitterTweets","twitterAverageTweetsPerDay","twitterRetweetTweets","twitterAverageRetweetTweetsPerDay","twitterReplyTweets","twitterAverageReplyTweetsPerDay","twitterFollowerToFollowingRatio","twitterRepliesToCompanyTweets","twitterAverageRepliesPerDay","twitterVideoViews","twitterAverageVideoViewsPerDay","twitterEstimatedImpressions","twitterEngagementRateByEstimatedImpression","twitterImpressions","youTubeSubscribers","youTubeVideos","youTubeLifetimeViews","youTubeComments","youTubePosts","youTubeAveragePostsPerDay","youTubePostViews","youTubeAveragePostViewsPerDay","youTubePostLikes"
"Seattle Seahawks",6909,"2022-11-01T00:00:00.000Z","2022-11-15T23:59:59.999Z","2022-10-17T00:00:00.000Z","2022-10-31T23:59:59.999Z",276,18.4,28370,1891.3333333333333,288831,19255.4,323092,21539.466666666667,1591.5862068965516,0.000619851880126273,87691,203,13.533333333333333,48,3.2,25,1.6666666666666667,2726.837,5891,392.73333333333335,5617642,374509.4666666667,15703012,0.020575160994591356,15703012,191000,4393,52044844,,86,5.733333333333333,1623723,108248.2,52716
```

--------------------------------

### Success Response (JSON)

Source: https://app.rivaliq.com/api-reference/index

Example of a successful API response in JSON format, containing positioning data for companies.

```json
HTTP/1.1 200 OK
{
  "positioning": [{
     "companyName": "Seattle Seahawks",
     "companyId": 6909,
     "twitterBio": "Official Twitter account of the Seattle Seahawks. #GoHawks",
     "youTubeDescription": "The official YouTube Channel of the Seattle Seahawks.",
     "youTubeTitle": "Seattle Seahawks",
     "youTubeKeywords": "National Football League, Seattle Seahawks, Professional Football, Seattle, CenturyLink Field, NFL",
     "instagramBio": "Official Instagram of the Seattle Seahawks 📸",
     "instagramFullName": "Seattle Seahawks",
     "homepageTitle": "Seahawks Home | Seattle Seahawks – seahawks.com",
     "homepageMetaDescription": "Seattle Seahawks Home: The official source of the latest Seahawks headlines, news, videos, photos, tickets, rosters, stats, schedule, and gameday information",
     "homepageMetaKeywords": "[ empty ]",
     "facebookDescription": "Official Facebook Fan Page of the National Football League's Seattle Seahawks. Twitter http://twitter.com/seahawks Instagram http://instagram.com/seahawks"
  }]
}
```

--------------------------------

### Error Response Examples

Source: https://app.rivaliq.com/api-reference/index

Illustrates various error responses from the API, including User Not Found, Landscape Not Found, and rate limit exceeded errors.

```HTTP
HTTP/1.1 404 Not Found
{
  "error": "UserNotFound"
}
```

```HTTP
HTTP/1.1 404 Not Found
{
  "error": "LandscapeNotFound"
}
```

```HTTP
HTTP/1.1 429 Too Many Requests
{
  "error": "ConcurrencyLimitExceeded"
}
```

```HTTP
HTTP/1.1 429 Too Many Requests
{
  "error": "PendingOperationConcurrencyLimitExceeded"
}
```

```HTTP
HTTP/1.1 429 Too Many Requests
{
  "error": "HourRateLimitExceeded"
}
```

--------------------------------

### Success Response (CSV)

Source: https://app.rivaliq.com/api-reference/index

Example of a successful API response in CSV format, providing positioning data for companies.

```csv
HTTP/1.1 200 OK
company_name,company_id,twitter_bio,facebook_description,youtube_title,youtube_description,youtube_keywords,instagram_full_name,instagram_bio,homepage_title,homepage_meta_description,homepage_meta_keywords
"Seattle Seahawks",6909,"The official twitter account of the Seattle Seahawks...","Official Facebook Fan Page of...","Seattle Seahawks","The official Youtube Channel of the Seattle Seahawks.","[ empty ]","Seattle Seahawks","The official Instagram of the Seattle Seahawks...","Seattle Seahawks","[ empty ]","[ empty ]"
```

--------------------------------

### GET /websites/app_rivaliq_api-reference

Source: https://app.rivaliq.com/api-reference/index

Retrieves a list of landscapes, each containing detailed information about companies, their social media presences, and associated company sets.

```APIDOC
## GET /websites/app_rivaliq_api-reference

### Description
This endpoint returns a list of landscapes. Each landscape object includes a focus company, a list of companies within that landscape, and defined company sets. Company objects contain details such as their primary URL, social media presences (Twitter, Facebook, YouTube, Instagram, TikTok), and historical data timestamps. It also includes information about company sets and tags defined for the landscape.

### Method
GET

### Endpoint
/websites/app_rivaliq_api-reference

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **landscapes** (Object[]) - List of landscape descriptions.
  - **id** (Number) - Landscape Id.
  - **name** (String) - Landscape name.
  - **focusCompanyId** (Number) - Id of the focus company for the landscape.
  - **companies** (Object[]) - List of companies in the landscape.
    - **id** (Number) - Id of the company.
    - **name** (String) - Name of the company.
    - **url** (String) - Primary URL of the company.
    - **companySets** (String[]) - List of names of company sets for the company.
    - **tags** (String[]) - List of tags for the company (deprecated; should use `companySets` instead since company set is the new name of tag).
    - **twitter** (Object) - Primary Twitter presence data.
      - **handle** (String) - Primary Twitter handle.
      - **nativeId** (String) - Primary Twitter native Id.
      - **url** (String) - URL of primary Twitter presence.
      - **postHistorySince** (String) - UTC start timestamp of post history.
      - **presenceHistorySince** (String) - UTC start timestamp of presence history.
    - **facebook** (Object) - Primary Facebook presence data.
      - **handle** (String) - Primary Facebook handle.
      - **nativeId** (String) - Primary Facebook native Id.
      - **url** (String) - URL of primary Facebook presence.
      - **postHistorySince** (String) - UTC start timestamp of post history.
      - **presenceHistorySince** (String) - UTC start timestamp of presence history.
    - **youTube** (Object) - Primary YouTube presence data.
      - **nativeId** (String) - Primary YouTube native Id.
      - **url** (String) - URL of primary YouTube presence.
      - **postHistorySince** (String) - UTC start timestamp of post history.
      - **presenceHistorySince** (String) - UTC start timestamp of presence history.
    - **instagram** (Object) - Primary Instagram presence data.
      - **handle** (String) - Primary Instagram handle.
      - **nativeId** (String) - Primary Instagram native Id.
      - **isBusinessAccount** (String) - Primary Instagram presence is a business account.
      - **url** (String) - URL of primary Instagram presence.
      - **postHistorySince** (String) - UTC start timestamp of post history.
      - **presenceHistorySince** (String) - UTC start timestamp of presence history.
    - **tikTok** (Object) - Primary TikTok presence data.
      - **url** (String) - URL of primary Tiktok presence.
      - **nativeId** (String) - Primary Tiktok native Id.
      - **postHistorySince** (String) - UTC start timestamp of post history.
      - **presenceHistorySince** (String) - UTC start timestamp of presence history.
      - **handle** (String) - Primary Tiktok handle.
  - **companySets** (Object[]) - List of names of company sets defined for the landscape.
    - **id** (String) - Id of the company set.
    - **name** (String) - Name of the company set.
  - **tags** (Object[]) - List of tags defined for the landscape (deprecated; should use `companySets` instead since company set is the new name of tag).
    - **id** (String) - Id of the tag.
    - **name** (String) - Name of the tag.

#### Response Example
```json
{
  "landscapes":[
     {
       "id": 1234,
       "name": "NFL",
       "focusCompanyId": 12347,
       "companies": [
           {
             "id": 12345,
             "name": "Arizona Cardinals",
             "url": "http://www.azcardinals.com/",
             "companySets": ["nfc"],
             "tags": ["nfc"],
             "twitter": {
               "handle": "AZCardinals",
               "nativeId": "389038362",
               "url": "https://twitter.com/AZCardinals",
               "postHistorySince": "2013-05-29T16:58:10.000Z",
               "presenceHistorySince": "2013-05-31T20:26:43.930Z"
             },
             "facebook": {
               "handle": "arizonacardinals",
               "nativeId": "102042542297",
               "url": "https://facebook.com/102042542297",
               "postHistorySince": "2013-05-24T18:27:43.000Z",
               "presenceHistorySince": "2013-05-31T20:26:45.300Z"
             },
             "youTube": {
               "nativeId": "UCzNfiKcvNjLHljohEkO83Rg",
               "url": "https://www.youtube.com/channel/UCzNfiKcvNjLHljohEkO83Rg",
               "postHistorySince": "2013-10-13T00:00:00.000Z",
               "presenceHistorySince": "2015-10-08T22:04:38.133Z"
             },
             "instagram": {
               "handle": "azcardinals",
               "nativeId": "20352627",
               "url": "https://instagram.com/azcardinals",
               "postHistorySince": "2014-02-17T00:00:00.000Z",
               "presenceHistorySince": "2014-03-19T03:45:56.871Z"
             },
             "tikTok": {
               "url": "https://www.tiktok.com/azcardinals",
               "nativeId": "6693285196621497349",
               "postHistorySince": "2019-05-04T00:00:00.000Z",
               "presenceHistorySince": "2021-05-04T20:04:51.573Z",
               "handle": "azcardinals"
             }
           },
           ...
       ],
       "companySets": [
           { "id": "___internal___focus", "name": "Only Focus Company" },
           { "id": "afc", "name": "afc" },
           { "id": "nfc", "name": "nfc" }
       ],
       "tags": [
         {
           "id": "___internal___focus",
           "name": "Only Focus Company"
         },
         {
           "id": "afc",
           "name": "afc"
         },
         {
           "id": "nfc",
           "name": "nfc"
         }
       ]
     }
  ]
}
```
```

--------------------------------

### Get Landscape

Source: https://app.rivaliq.com/api-reference/index

Retrieves a single landscape by its ID. Requires a valid API key and landscape ID.

```APIDOC
## GET /api/v3/landscapes/{landscapeId}

### Description
Retrieves a single landscape by its ID.

### Method
GET

### Endpoint
/api/v3/landscapes/{landscapeId}

### Parameters
#### Path Parameters
- **landscapeId** (Number) - Required - The ID of the landscape to retrieve.

#### Query Parameters
- **apiKey** (String) - Required - The user's unique API key.
- **v** (String) - Optional - Cache buster parameter (value ignored). Used to bypass cache.

### Response
#### Success Response (200)
*Response body structure for a successful landscape retrieval would be detailed here.*

#### Response Example
*Example response body for a successful landscape retrieval would be detailed here.*

#### Error Responses
*Error responses for this endpoint would be detailed here, similar to the post_tags endpoint.*

#### Error Response Example
*Example error response body would be detailed here.*
```

--------------------------------

### GET /landscape/status

Source: https://app.rivaliq.com/api-reference/index

Checks the data freshness status of a landscape and initiates an update if necessary. Requires landscape ID and an API key.

```APIDOC
## GET /landscape/status

### Description
Checks landscape data freshness status, initiates update if necessary.

### Method
GET

### Endpoint
/landscape/status

### Parameters
#### Path Parameters
- **landscapeId** (Number) - Required - Landscape Id

#### Query Parameters
- **apiKey** (String) - Required - The user's unique API key
- **v** (String) - Optional - Cache buster (value ignored).

### Response
#### Success Response (200)
- **status** (Number) - Data freshness status (1 = ready, 2 = update pending)

#### Response Example
```json
{
  "status": 1
}
```

### Error Handling
- **User Not Found**: HTTP/1.1 404 Not Found
- **Landscape Not Found**: HTTP/1.1 404 Not Found
- **Concurrency Limit Exceeded**: HTTP/1.1 429 Too Many Requests
- **Hour Rate Limit Exceeded**: HTTP/1.1 429 Too Many Requests
```

--------------------------------

### List Available Landscapes (HTTP)

Source: https://app.rivaliq.com/api-reference/index

Retrieves a list of available landscapes on the Rival IQ platform. This endpoint requires an apiKey for authentication.

```HTTP
GET /api/v3/landscapes?apiKey=YOUR_API_KEY

HTTP/1.1 200 OK
{
  "landscapes": [
    {
      "id": "some-landscape-id",
      "name": "Example Landscape"
    }
  ]
}
```

--------------------------------

### GET /websites/app_rivaliq_api-reference/social_posts/bulk_instagram_insights

Source: https://app.rivaliq.com/api-reference/index

Initiates retrieval of Instagram Insight Posts for all companies within a specified landscape and time period. A token is issued upon successful request, which can be used with the Bulk Download Status API to get the data URL.

```APIDOC
## GET /websites/app_rivaliq_api-reference/social_posts/bulk_instagram_insights

### Description
Initiates retrieval of the Instagram Insight Posts for all companies within the landscape within a given time period. Upon a successful request to this API, a token will be issued. This token can then be used to retrieve the URL for the actual data by passing the token to the Bulk Download Status API.

**Warning**: Please note that this feature is currently in beta testing and may undergo further changes to improve its functionality and user experience.

**Note**: Rival IQ may add or reorder columns in the CSV outputs; callers should not depend on column order but rather on column name.

### Method
GET

### Endpoint
`/websites/app_rivaliq_api-reference/social_posts/bulk_instagram_insights`

### Parameters
#### Path Parameters
- **landscapeId** (Number) - Required - Landscape Id

#### Query Parameters
- **searchTerm** (String) - Optional - Search term to filter top content results
- **mediaType** (String) - Optional - Media type. Default value: `any`. Allowed values: `any`, `photo`, `video`, `status`, `link`, `event`, `music`
- **apiKey** (String) - Required - The user's unique API key
- **postTag** (String) - Optional - Comma-separated list of post tag IDs. If `all` is specified anywhere in the list, then all posts are included. Default value: `all`
- **format** (String) - Optional - Data format. Note that CSV column order is not guaranteed over time, always access data by column name, not column index. Default value: `json`. Allowed values: `csv`, `json`
- **timePeriod** (String) - Required - Named time period ("last7Days", "last30Days", "last90Days", "yesterday", "thisWeek", "lastWeek", "thisMonth", "lastMonth"), mutually exclusive with `mainPeriodStart`, `mainPeriodEnd`, `comparePeriodStart`, and `comparePeriodEnd` parameters.
- **mainPeriodStart** (String) - Optional - UTC main period start date (inclusive) e.g. "2015-11-23"
- **mainPeriodEnd** (String) - Optional - UTC main period end date (inclusive)
- **companyId** (String) - Optional - Comma-separated list of company IDs. Mutually exclusive with `companySet` parameter. Returned data is restricted to only these companies.
- **companySet** (String) - Optional - Optional company set to apply when running report
- **tag** (String) - Optional - Optional tag to apply when running report (deprecated; please use `companySet` instead since company set is the new name of tag)
- **includePostTags** (String) - Optional - If set to `true` and `format`=`json`: Return an array of applicable post tag objects. If set to `true` and `format`=`csv`: Return post tags as formatted row headers, with with value of 1 if tag is present on post, or 0 if it is not present on post. Default value: `false`
- **v** (String) - Optional - Cache buster (value ignored). This parameter has no effect on the data retrieved or the response generated by the Rival IQ server. This can be used to ensure intermediate layers (proxies, etc) pass the request through rather than return previously cached responses.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (202 Accepted)
- **token** (String) - Bulk download token; one should use it to call Bulk Download Status API to get the download status.

#### Response Example
```json
{
  "token": "gAaBbCcDdEeF"
}
```

#### Error Responses
- **User Not Found** (404 Not Found)
```json
{
  "error": "UserNotFound"
}
```
- **Landscape Not Found** (404 Not Found)
```json
{
  "error": "LandscapeNotFound"
}
```
- **Concurrency Limit Exceeded** (429 Too Many Requests)
```json
{
  "error": "ConcurrencyLimitExceeded"
}
```
- **Pending Operation Concurrency Limit Exceeded** (429 Too Many Requests)
```json
{
  "error": "PendingOperationConcurrencyLimitExceeded"
}
```
- **Hour Rate Limit Exceeded** (429 Too Many Requests)
```json
{
  "error": "HourRateLimitExceeded"
}
```
```

--------------------------------

### Get Landscape Companies

Source: https://app.rivaliq.com/api-reference/index

Retrieves a list of companies associated with a specific landscape.

```APIDOC
## GET /landscapes/{landscapeId}/companies

### Description
Retrieves a list of companies associated with a specific landscape.

### Method
GET

### Endpoint
/landscapes/{landscapeId}/companies

### Parameters
#### Path Parameters
- **landscapeId** (Number) - Required - The unique identifier for the landscape.

### Request Example
```
GET /landscapes/123/companies
```

### Response
#### Success Response (200)
- **companies** (Array of Objects) - A list of companies within the specified landscape.
  - Each object contains company details similar to the 'Get Company Information' endpoint.

#### Response Example
```json
{
  "companies": [
    {
      "id": 12345,
      "name": "Arizona Cardinals",
      "url": "http://www.azcardinals.com/",
      "companySets": ["nfc"],
      "tags": ["nfc"],
      "twitter": {
        "handle": "AZCardinals",
        "nativeId": "389038362",
        "url": "https://twitter.com/AZCardinals",
        "postHistorySince": "2013-05-29T16:58:10.000Z",
        "presenceHistorySince": "2013-05-31T20:26:43.930Z"
      },
      "facebook": {
        "handle": "arizonacardinals",
        "nativeId": "102042542297",
        "url": "https://facebook.com/102042542297",
        "postHistorySince": "2013-05-24T18:27:43.000Z",
        "presenceHistorySince": "2013-05-31T20:26:45.300Z"
      },
      "youTube": {
        "nativeId": "UCzNfiKcvNjLHljohEkO83Rg",
        "url": "https://www.youtube.com/channel/UCzNfiKcvNjLHljohEkO83Rg",
        "postHistorySince": "2013-10-13T00:00:00.000Z",
        "presenceHistorySince": "2015-10-08T22:04:38.133Z"
      },
      "instagram": {
        "handle": "azcardinals",
        "nativeId": "20352627",
        "url": "https://instagram.com/azcardinals",
        "postHistorySince": "2014-02-17T00:00:00.000Z",
        "presenceHistorySince": "2014-03-19T03:45:56.871Z"
      },
      "tikTok": {
        "url": "https://www.tikTok.com/azcardinals",
        "nativeId": "6693285196621497349",
        "postHistorySince": "2019-05-04T00:00:00.000Z",
        "presenceHistorySince": "2021-05-04T20:04:51.573Z",
        "handle": "azcardinals"
      }
    }
    // ... more companies
  ]
}
```

#### Error Responses
- **404 Not Found** - LandscapeNotFound: Returned when the specified landscape ID does not exist.
- **404 Not Found** - CompanyNotFound: Returned when no companies are found for the specified landscape.
- **429 Too Many Requests** - ConcurrencyLimitExceeded: Returned when the concurrency limit is exceeded.
- **429 Too Many Requests** - HourRateLimitExceeded: Returned when the hourly rate limit is exceeded.
```

--------------------------------

### Create Landscape API Request and Response

Source: https://app.rivaliq.com/api-reference/index

Demonstrates how to create a new landscape using the Rival IQ API. Includes details on required parameters, request body, and the success response structure.

```HTTP
HTTP/1.1 200 OK
{
  "landscape":{
     "id": 1234,
     "name": "NFL",
     "focusCompanyId": null,
     "companies": []
     "companySets": [
         { "id": "___internal___focus", "name": "Only Focus Company" }
     ],
     "tags": [
         { "id": "___internal___focus", "name": "Only Focus Company" }
     ]
  }
}
```

```HTTP
HTTP/1.1 400 Bad Request
{
  "error": "InvalidEntityBody"
}
```

```HTTP
HTTP/1.1 404 Not Found
{
  "error": "UserNotFound"
}
```

```HTTP
HTTP/1.1 415 Unsupported Media Type
{
  "error": "InvalidContentType"
}
```

--------------------------------

### CSV Data Example for Social Posts

Source: https://app.rivaliq.com/api-reference/index

This snippet shows an example of CSV data representing social post insights. It includes various metrics like reach, engagement, likes, comments, shares, impressions, and video views, along with post details and media information. The data is structured with a header row followed by a data row.

```csv
post_id,native_id,company_id,company_name,presence_handle,presence_reach,published_at,captured_at,message,post_url,num_carousel_children,num_carousel_photo_children,num_carousel_video_children,reach_organic,reach_paid,engagement_total,engagement_total_organic,engagement_total_paid,likes,likes_organic,likes_paid,comments,comments_organic,comments_paid,saves,saves_organic,saves_paid,shares,shares_organic,shares_paid,impressions,impressions_organic,impressions_paid,video_views,video_views_organic,video_views_paid,video_view_rate_by_impression,video_view_rate_by_impression_organic,video_view_rate_by_impression_paid,video_view_rate_by_reach,video_view_rate_by_reach_organic,video_view_rate_by_reach_paid,social_engagement_total,social_engagement_total_organic,social_engagement_total_paid,follows,profile_views,profile_interactions,profile_bio_link_clicks,profile_other_interactions,paid_link_clicks,total_spend,media_type,image_url,engagement_rate_by_impression,engagement_rate_by_impression_organic,engagement_rate_by_impression_paid,engagement_rate_by_reach,engagement_rate_by_reach_organic,engagement_rate_by_reach_paid,social_engagement_rate_by_reach_organic,social_engagement_rate_by_reach_paid,social_engagement_rate_by_impression,social_engagement_rate_by_impression_organic,social_engagement_rate_by_impression_paid,post_reach_rate_by_presence_reach_organic,post_reach_rate_by_presence_reach_paid,post_tag_bar,post_tag_foo,post_tag_contests,post_tag_ugc
18.165012918,17988062861436128,1137028,"Rival IQ",@rival_iq,1633,2024-03-06T20:21:40.000Z,2024-03-06T23:53:37.457Z,"Purchasing Instagram followers may seem tempting, and while some folks see it as a means to an end (more followers lead to more exposure, which leads to gaining more “real” followers), this just isn’t the case. When you purchase followers, you’re often buying bots or inactive Instagram accounts, neither of which will interact with any of your posts. So, while your follower count is growing, it won’t be reflected in your engagement.",https://www.instagram.com/p/C4L59M3OgiR,3,3,0,35,0,6,6,0,5,5,0,0,0,0,1,1,0,,,0,37,37,0,,,0,,,0,,,0,5,5,0,,,,,,0,0,Carousel,https://d2s3bcuxxtimee.cloudfront.net/C4L59M3OgiR?postNativeId=17988062861436128,0.16216216216216217,0.16216216216216217,0,0.17142857142857143,0.17142857142857143,0,0.14285714285714285,0,0.13513513513513514,0.13513513513513514,0,0.021432945499081445,0,0,0,0,0
```

--------------------------------

### Success Response: Get Posts (CSV)

Source: https://app.rivaliq.com/api-reference/index

Returns post data in CSV format, with each row representing a post and columns for various metrics. Post tags are included as separate columns with a specific header format.

```csv
HTTP/1.1 200 OK
post_id,native_id,company_id,company_name,presence_handle,presence_reach,published_at,captured_at,media_type,message,post_url,media_url,reach,engagement_total,social_engagement_total,likes,comments,shares,impressions,video_views,video_length,video_average_time_watched,video_view_time,video_full_view_rate,engagement_rate_by_impression,engagement_rate_by_presence_reach,social_engagement_rate_by_impression,social_engagement_rate_by_presence_reach
21.2122,7364086013376924959,1404385,"pets of rival iq",petsofrivaliq,0,2024-05-01T17:37:08.000Z,2024-06-30T23:03:15.415Z,Video,,https://www.tiktok.com/@petsofrivaliq/video/7364086013376924959,https://www.tiktok.com/player/v1/7364086013376924959?music_info=1&description=1&autoplay=1&loop=1&utm_campaign=tt4d_open_api&utm_source=7105971858289197057,157,1,1,1,0,0,171,171,15000,1080,189000,0.0057,0.005847953216374269,,0.005847953216374269,
```

--------------------------------

### Error Response - Invalid Time Period

Source: https://app.rivaliq.com/api-reference/index

Example of an error response when an invalid time period is specified for a query.

```json
HTTP/1.1 400 Bad Request
{
  "error": "InvalidTimePeriod"
}
```

--------------------------------

### Landscape and Company Management

Source: https://app.rivaliq.com/api-reference/index

This section details endpoints related to managing landscapes and associated company data within the Rival IQ platform. It includes information on URL parameters, query parameters, and request body structures.

```APIDOC
## URL Parameter

Field | Type | Description
---|---|---
landscapeId | Number | Landscape Id

## Query Parameter

Field | Type | Description
---|---|---
apiKey | String | The user's unique API key
v optional | String | Cache buster (value ignored). This parameter has no effect on the data retrieved or the response generated by the Rival IQ server. This can be used to ensure intermediate layers (proxies, etc) pass the request through rather than return previously cached responses.

## Request Body

Field | Type | Description
---|---|---
name optional | String | Landscape Name
focusCompanyId optional | Number | Landscape Focus Company
```

--------------------------------

### GET /social_posts

Source: https://app.rivaliq.com/api-reference/index

Returns the top 500 social posts for all companies within the landscape for a given time period.

```APIDOC
## GET /social_posts

### Description
Returns the top 500 posts for for all companies within the landscape within a given time period.

Note: Rival IQ may add or reorder columns in the CSV outputs; callers should not depend on column order but rather on column name.

### Method
GET

### Endpoint
`/social_posts`

### Parameters
#### Path Parameters
- **landscapeId** (Number) - Required - Landscape Id

#### Query Parameters
- **searchTerm** (String) - Optional - Search term to filter top content results
- **postType** (String) - Optional - Post type. Allowed values: `any`, `photo`, `link`, `video`, `status`. Default: `any`
- **apiKey** (String) - Required - The user's unique API key
- **channel** (String) - Optional - Comma-separated list of social channels to include. Default: `all`. Allowed values: `all`, `facebook`, `instagram`, `twitter`, `youtube`, `tiktok`
- **postTag** (String) - Optional - Comma-separated list of post tag IDs. Default: `all`
- **format** (String) - Optional - Data format. Allowed values: `csv`, `json`. Default: `json`
- **companySet** (String) - Optional - Optional company set to apply when running report
- **tag** (String) - Optional - Optional tag to apply when running report (deprecated; please use `companySet` instead)
- **timePeriod** (String) - Required - Named time period (e.g., "last7Days", "last30Days"), mutually exclusive with date range parameters.
- **mainPeriodStart** (String) - Required - UTC main period start date (inclusive) e.g. "2015-11-23"
- **mainPeriodEnd** (String) - Required - UTC main period end date (inclusive)
- **comparePeriodStart** (String) - Required - UTC compare period start date (inclusive)
- **comparePeriodEnd** (String) - Required - UTC compare period end date (inclusive)
- **twitterTweetType** (String) - Optional - Twitter tweet type filter. Allowed values: `all`, `normal`, `reply`, `retweet`. Default: `all`
- **companyId** (String) - Optional - Comma-separated list of company IDs. Mutually exclusive with `companySet`.
- **updatedSince** (String) - Optional - UTC time cut-off
- **includePostTags** (String) - Optional - If set to `true` and `format`=`json`: Return an array of applicable post tag objects. If set to `true` and `format`=`csv`: Return post tags as formatted row headers. Default: `false`
- **v** (String) - Optional - Cache buster (value ignored).

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200 OK)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Responses
- **User Not Found** (404 Not Found): `{"error": "UserNotFound"}`
- **Landscape Not Found** (404 Not Found): `{"error": "LandscapeNotFound"}`
- **Concurrency Limit Exceeded** (429 Too Many Requests): `{"error": "ConcurrencyLimitExceeded"}`
- **Pending Operation Concurrency Limit Exceeded** (429 Too Many Requests): `{"error": "PendingOperationConcurrencyLimitExceeded"}`
- **Hour Rate Limit Exceeded** (429 Too Many Requests): `{"error": "HourRateLimitExceeded"}
```

--------------------------------

### POST /companies/follow

Source: https://app.rivaliq.com/api-reference/index

Allows users to follow a company by providing its URL. This action is available to all users.

```APIDOC
## POST /companies/follow

### Description
Allows users to follow a company by providing its URL. This action is available to all users.

### Method
POST

### Endpoint
/companies/follow

### Parameters
#### Request Body
- **url** (String) - Required - The URL of the company to follow.

### Response
#### Success Response (200)
- **message** (String) - Confirmation message indicating the company is being followed.

#### Response Example
```json
{
  "message": "Company is now being followed"
}
```

#### Error Responses
- **400 Bad Request**: `{"error": "InvalidEntityBody"}`
- **404 Not Found**: `{"error": "UserNotFound"}`
- **415 Unsupported Media Type**: `{"error": "InvalidContentType"}`
- **429 Too Many Requests**: `{"error": "ConcurrencyLimitExceeded"}` or `{"error": "HourRateLimitExceeded"}`
```