---
title: "User Guide for API Endpoints"
slug: "user-guide-for-api-endpoints"
updated: 2024-08-07T09:56:48Z
published: 2024-08-07T09:56:48Z
canonical: "docs.viewlift.com/user-guide-for-api-endpoints"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viewlift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Guide for API Endpoints

## **Overview**

This document provides detailed descriptions of various API endpoints, including their arguments, type details, and sample queries/mutations. It serves as a comprehensive guide to help developers understand and use these APIs effectively.

### **Endpoints and Parameters**

**1. listUsers**

**Description**: API for exporting user details. This API uses cursor-based pagination and currently only supports forward pagination.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| first | Int | Number of users to return. |
| after | String | Cursor for pagination. |
| emails | [String] | Filter by specific email addresses. |
| dateRanges | [ListUsersDateRange] | Filter by user creation date ranges. |
| anonymizedDate | [ListUsersDateRange] | Filter by user anonymized date ranges. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| usersCount | Int | Total number of users. |
| users | [User] | List of users. |

**2. listUserWatched**

**Description**: API for returning the history of streams watched by users for the specified time range. This API uses offset-based pagination.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| offset | Int | Offset for pagination. Default is 0. |
| limit | Int | Number of records to return. Default is 10. |
| watchTimeFrom | Date | Filter by watch time start date. |
| watchTimeTo | Date | Filter by watch time end date. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| totalCount | Int | Total count of watched streams. |
| edges | [WatchedStreamEdge] | Watched stream edges. |
| totalWatchedStreams | Int | Total number of watched streams. |
| watchedStreams | [WatchedStream] | List of watched streams. |

**3. listContents**

**Description**: API for exporting all content metadata based on the filter criteria. This API uses cursor-based pagination and currently only supports forward pagination.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| first | Int | Number of contents to return. Default is 100. |
| after | String | Cursor for pagination. |
| updatedRange | DateRange | Filter by content update date range. |
| publishDateRange | DateRange | Filter by content publish date range. |
| type | ContentType | Filter by content type. |
| status | Status | Filter by content status. |
| includeUnpublished | Boolean | Include unpublished content. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| contentCount | Int | Total number of content items. |
| contents | [Content] | List of content items. |

**4. listPayments**

**Description**: API for exporting payment records based on the filter criteria. This API uses offset-based pagination.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| offset | Int | Offset for pagination. Default is 0. |
| limit | Int | Number of records to return. Default is 10. |
| startDate | Date | Filter by start date of payment records. |
| endDate | Date | Filter by end date of payment records. |
| monetizationModels | [MonetizationModelType] | Filter by monetization models. |
| dateRanges | [ListPaymentsDateRange] | Filter by payment date ranges. |
| type | BillingRecordType | Filter by billing record type. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| billingHistory | [BillingHistory] | List of billing history records. |

**5. listSubscriptions**

**Description**: Deprecated API for exporting all subscriptions. Use listPurchases API instead.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| first | Int | Number of subscriptions to return. |
| after | String | Cursor for pagination. |
| statuses | [SubscriptionStatus] | Filter by subscription statuses. |
| dateRanges | [ListSubscriptionsDateRange] | Filter by subscription date ranges. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| subscriptions | [VLSubscription] | List of subscriptions. |

**6. listPurchases**

**Description**: API for exporting all types of purchases (SUBSCRIPTION, BUY, RENT). This API uses cursor-based pagination.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| first | Int | Number of purchases to return. |
| after | String | Cursor for pagination. |
| type | PurchaseType | Filter by purchase type. |
| dateRanges | [ListPurchasesDateRange] | Filter by purchase date ranges. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| purchasesCount | Int | Total number of purchases. |
| pageInfo | PageInfo | Pagination information. |
| purchases | [Purchase] | List of purchases. |

**7. listUserWatchedVideoRuntime**

**Description**: API for returning the user runtime spent on specific videos.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| watchTimeFrom | Date | Filter by watch time start date. |
| watchTimeTo | Date | Filter by watch time end date. |
| videoId | String | Filter by specific video ID. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| videoWatchedRunTimes | [VideoWatchedRunTimeResponse] | List of videos watched runtime details. |

**8. listUserWatchedFastchannel**

**Description**: API for returning the user runtime spent on fast channels.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| offset | Int | Offset for pagination. Default is 0. |
| limit | Int | Number of records to return. Default is 10. |
| watchTimeFrom | Date | Filter by watch time start date. |
| watchTimeTo | Date | Filter by watch time end date. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| totalCount | Int | Total number of fast channel streams. |
| fastchannelWatchedStreams | [FastchannelWatchedStreams] | List of fast channels watched streams. |

**9. listFastchannelContent**

**Description**: API for returning details of fast channels and associated videos.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| offset | Int | Offset for pagination. Default is 0. |
| limit | Int | Number of records to return. Default is 10. |
| date_from | Date | Filter by start date. |
| date_to | Date | Filter by end date. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| totalCount | Int | Total count of fast channel contents. |
| listFastchannelContentDetail | [listFastchannelContentDetail] | List of fast channel content details. |

**10. listMonetizationModel**

**Description**: API for returning monetization model details based on the specified criteria.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| first | Int | Number of records to return. Default is 100. |
| after | Int | Cursor for pagination. Default is 10. |
| updatedRange | DateRange | Filter by updated date range. |

**Type Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| pageInfo | PageInfo | Pagination information. |
| listMonetizationModelDetail | [listMonetizationModelDetail] | List of monetization model details. |

**11. login**

**Description**: API for user login.

**Arguments**:

| **Argument** | **Type** | **Description** |
| --- | --- | --- |
| email | String | User email address. Required. |
| password | String | User password. Required. |
| loginType | LoginType | Type of login (default is "admin"). |

**Union Details**:

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| LoginResponse | Union | Can be either LoginSuccess or LoginError. |

**Type Definitions**

**PageInfo**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| endCursor | String | Cursor for the end of the current page. |
| hasNextPage | Boolean | Indicates if there is a next page. |

**User**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the user. |
| email | String | Email address of the user. |
| name | String | Name of the user. |

**ListUsersDateRange**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| start | Date | Start date of the range. |
| end | Date | End date of the range. |

**WatchedStreamEdge**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| node | WatchedStream | The watched stream. |

**WatchedStream**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the stream. |
| userId | ID | User ID who watched the stream. |
| videoId | ID | Video ID of the watched stream. |
| watchedAt | DateTime | Timestamp when the stream was watched. |
| duration | Int | Duration of the watched stream. |

**DateRange**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| start | Date | Start date of the range. |
| end | Date | End date of the range. |

**ContentType**

Enum representing the type of content (e.g., VIDEO, ARTICLE).

**Status**

Enum representing the status of the content (e.g., PUBLISHED, DRAFT).

**BillingHistory**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the billing record. |
| amount | Float | Amount billed. |
| date | Date | Billing date. |

**MonetizationModelType**

Enum representing the type of monetization model.

**ListPaymentsDateRange**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| start | Date | Start date of the range. |
| end | Date | End date of the range. |

**BillingRecordType**

Enum representing the type of billing record.

**SubscriptionStatus**

Enum representing the status of a subscription.

**ListSubscriptionsDateRange**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| start | Date | Start date of the range. |
| end | Date | End date of the range. |

**VLSubscription**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the subscription. |
| status | SubscriptionStatus | Status of the subscription. |
| startDate | Date | Subscription start date. |
| endDate | Date | Subscription end date. |

**PurchaseType**

Enum representing the type of purchase (e.g., SUBSCRIPTION, BUY, RENT).

**ListPurchasesDateRange**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| start | Date | Start date of the range. |
| end | Date | End date of the range. |

**Purchase**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the purchase. |
| type | PurchaseType | Type of the purchase. |
| date | Date | Purchase date. |
| amount | Float | Amount of the purchase. |

**VideoWatchedRunTimeResponse**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| videoId | String | ID of the video. |
| runtime | Int | Runtime spent on the video. |

**FastchannelWatchedStreams**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the stream. |
| userId | ID | User ID who watched the stream. |
| channelId | ID | Fast channel ID of the watched stream. |
| watchedAt | DateTime | Timestamp when the stream was watched. |
| duration | Int | Duration of the watched stream. |

**listFastchannelContentDetail**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the content. |
| title | String | Title of the content. |
| description | String | Description of the content. |
| publishDate | Date | Publish date of the content. |

**listMonetizationModelDetail**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| id | ID | Unique identifier for the monetization model. |
| name | String | Name of the monetization model. |
| description | String | Description of the monetization model. |

**LoginType**

Enum representing the type of login (e.g., ADMIN, USER).

**LoginSuccess**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| token | String | Authentication token. |
| user | User | User details. |

**LoginError**

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| message | String | Error message. |

**Sample Queries and Mutations**

**Sample Query for listUsers**

```plaintext
query {
    listUsers(first: 10, after: "cursor123", emails: ["user1@example.com", "user2@example.com"], dateRanges: [{start: "2021-01-01", end: "2021-12-31"}]) {
        pageInfo {
            endCursor
            hasNextPage
        }
        usersCount
        users {
            id
            email
            name
        }
    }
}
```

**Sample Query for listUserWatched**

```plaintext
{
    listUserWatched(offset: 0, limit: 10, watchTimeFrom: "2021-01-01", watchTimeTo: "2021-12-31") {
        pageInfo {
            endCursor
            hasNextPage
        }
        totalCount
        edges {
            node {
                id
                userId
                videoId
                watchedAt
                duration
            }
        }
        totalWatchedStreams
        watchedStreams {
            id
            userId
            videoId
            watchedAt
            duration
        }
    }
}
```

**Sample Query for listContents**

```plaintext
{
    listContents(first: 100, after: "cursor456", updatedRange: {start: "2021-01-01", end: "2021-12-31"}, publishDateRange: {start: "2021-01-01", end: "2021-12-31"}, type: VIDEO, status: PUBLISHED, includeUnpublished: false) {
        pageInfo {
            endCursor
            hasNextPage
        }
        contentCount
        contents {
            id
            title
            description
            publishDate
        }
    }
}
```

## FAQ (Frequently Asked Questions)

**Q1: What is cursor-based pagination?**

**Ans:** Cursor-based pagination allows for efficient data retrieval by using a cursor (a unique identifier) to mark the starting point of the next set of results. It supports forward pagination only.

**Q2: What is offset-based pagination?**

**Ans:** Offset-based pagination uses an offset value to specify the starting point for the set of results and a limit to specify the number of results to return. It is suitable for scenarios where you need to skip a fixed number of records.

### `listUsers` API

**Q3: What does the** `first` **argument do?**

**Ans:** The `first` argument specifies the number of records to return in the query. For example, `first: 10` will return the first 10 users.

**Q4: How does the** `after` **argument work in pagination?**

**Ans:** The `after` argument takes a cursor value that marks the starting point for the next set of results. This is used to retrieve subsequent pages of results.

**Q5: Can I filter users by their email addresses?**

**Ans:** Yes, you can filter users by providing an array of email addresses to the `emails` argument.

### `listUserWatched` API

**Q6: What time format should I use for** `watchTimeFrom` **and** `watchTimeTo`?

**Ans:** The `watchTimeFrom` and `watchTimeTo` arguments should be provided in a standard date format, such as `YYYY-MM-DD`.

**Q7: What is the default limit of results returned by this API?**

**Ans:** The default limit is 10 results per query.

**Q8: Can I retrieve watched streams for a specific time range?**

**Ans:** Yes, you can specify a time range using the `watchTimeFrom` and `watchTimeTo` arguments to filter the watched streams.

### `listContents` API

**Q9: How can I include unpublished content in the results?**

**Ans:** To include unpublished content, set the `includeUnpublished` argument to `true`.

**Q10: What types of content can be retrieved using this API?**

**Ans:** You can retrieve various content types by specifying the `type` argument (e.g., VIDEO, ARTICLE).

**Q11: What does the** `updatedRange` **argument do?**

**Ans:** The `updatedRange` argument filters content based on the updated date range, allowing you to retrieve content updated within a specific period.

### `listPayments` API

**Q12: What is the purpose of the** `monetizationModels` argument?

**Ans:** The `monetizationModels` argument allows you to filter payments based on different monetization models (e.g., subscription, one-time payment).

**Q13: How do I specify a date range for payments?**

**Ans:** You can specify a date range using the `startDate` and `endDate` arguments.

### `listSubscriptions` API

**Q14: Is this API still supported?**

**Ans:** No, this API is deprecated. Please use the `listPurchases` API instead.

**Q15: How can I filter subscriptions by their status?**

**Ans:** You can filter subscriptions by providing an array of statuses to the `statuses` argument.

### `listPurchases` API

**Q16: What types of purchases can I retrieve?**

**Ans:** You can retrieve different types of purchases by specifying the `type` argument (e.g., SUBSCRIPTION, BUY, RENT).

**Q17: Can I filter purchases by a date range?**

**Ans:** Yes, you can filter purchases by providing a date range using the `dateRanges` argument.

### `login` Mutation

**Q18: What types of login are supported?**

**Ans:** The `loginType` argument supports different types of login, with the default being "**admin**".

**Q19: What does the** `LoginResponse` **union represent?**

**Ans:** The `LoginResponse` union can be either `LoginSuccess`, which includes the authentication token and user details, or `LoginError`, which includes an error message.

**Q20: What should I do if I receive a** `LoginError`?

**Ans:** Check the `message` field in the `LoginError` response for details about the error and ensure that the provided email and password are correct.

**Q: Why am I getting an empty response when using** `listUsers`**?**

**Ans:** Ensure that the arguments provided (e.g., dateRanges, emails) match existing user data. Also, check if the cursor value in the `after` argument is correct.

**Q: What should I do if my** `listPayments` **query returns no results?**

**Ans:** Verify that the date range and monetization model filters are correctly set and match the existing payment records.