AniList APIv2 Docs
  • README
  • docs
    • index
    • guide
      • Considerations
      • Introduction
      • Rate Limiting
      • Terms of Use
      • auth
        • Authenticated Requests
        • Authorization Code Grant
        • Implicit Grant
        • Getting Started
      • graphql
        • Connections
        • Errors
        • What is GraphQL?
        • Mutations
        • Pagination
        • What's Next?
        • queries
          • Queries
          • Media List
          • Media
          • User
      • migration
        • version-1
          • Migrating from API v1
          • Api v1 to Api v2 migration queries
    • reference
      • API Reference
      • Root Mutation
      • Root Query
      • enum
        • ActivitySort
        • ActivityType
        • AiringSort
        • CharacterRole
        • CharacterSort
        • ExternalLinkMediaType
        • ExternalLinkType
        • LikeableType
        • MediaFormat
        • MediaListSort
        • MediaListStatus
        • MediaRankType
        • MediaRelation
        • MediaSeason
        • MediaSort
        • MediaSource
        • MediaStatus
        • MediaTrendSort
        • MediaType
        • ModActionType
        • ModRole
        • NotificationType
        • RecommendationRating
        • RecommendationSort
        • ReviewRating
        • ReviewSort
        • RevisionHistoryAction
        • ScoreFormat
        • SiteTrendSort
        • StaffLanguage
        • StaffSort
        • StudioSort
        • SubmissionSort
        • SubmissionStatus
        • ThreadCommentSort
        • ThreadSort
        • UserSort
        • UserStaffNameLanguage
        • UserStatisticsSort
        • UserTitleLanguage
      • input
        • AiringScheduleInput
        • AniChartHighlightInput
        • CharacterNameInput
        • FuzzyDateInput
        • ListActivityOptionInput
        • MediaExternalLinkInput
        • MediaListOptionsInput
        • MediaTitleInput
        • NotificationOptionInput
        • StaffNameInput
      • object
        • ActivityLikeNotification
        • ActivityMentionNotification
        • ActivityMessageNotification
        • ActivityReply
        • ActivityReplyLikeNotification
        • ActivityReplyNotification
        • ActivityReplySubscribedNotification
        • AiringNotification
        • AiringProgression
        • AiringSchedule
        • AiringScheduleConnection
        • AiringScheduleEdge
        • AniChartUser
        • Character
        • CharacterConnection
        • CharacterEdge
        • CharacterImage
        • CharacterName
        • CharacterSubmission
        • CharacterSubmissionConnection
        • CharacterSubmissionEdge
        • Deleted
        • Favourites
        • FollowingNotification
        • FormatStats
        • FuzzyDate
        • GenreStats
        • InternalPage
        • ListActivity
        • ListActivityOption
        • ListScoreStats
        • Media
        • MediaCharacter
        • MediaConnection
        • MediaCoverImage
        • MediaDataChangeNotification
        • MediaDeletionNotification
        • MediaEdge
        • MediaExternalLink
        • MediaList
        • MediaListCollection
        • MediaListGroup
        • MediaListOptions
        • MediaListTypeOptions
        • MediaMergeNotification
        • MediaRank
        • MediaStats
        • MediaStreamingEpisode
        • MediaSubmission
        • MediaSubmissionComparison
        • MediaSubmissionEdge
        • MediaTag
        • MediaTitle
        • MediaTrailer
        • MediaTrend
        • MediaTrendConnection
        • MediaTrendEdge
        • MessageActivity
        • ModAction
        • NotificationOption
        • Page
        • PageInfo
        • ParsedMarkdown
        • Recommendation
        • RecommendationConnection
        • RecommendationEdge
        • RelatedMediaAdditionNotification
        • Report
        • Review
        • ReviewConnection
        • ReviewEdge
        • RevisionHistory
        • ScoreDistribution
        • SiteStatistics
        • SiteTrend
        • SiteTrendConnection
        • SiteTrendEdge
        • Staff
        • StaffConnection
        • StaffEdge
        • StaffImage
        • StaffName
        • StaffRoleType
        • StaffStats
        • StaffSubmission
        • StatusDistribution
        • Studio
        • StudioConnection
        • StudioEdge
        • StudioStats
        • TagStats
        • TextActivity
        • Thread
        • ThreadCategory
        • ThreadComment
        • ThreadCommentLikeNotification
        • ThreadCommentMentionNotification
        • ThreadCommentReplyNotification
        • ThreadCommentSubscribedNotification
        • ThreadLikeNotification
        • User
        • UserActivityHistory
        • UserAvatar
        • UserCountryStatistic
        • UserFormatStatistic
        • UserGenreStatistic
        • UserLengthStatistic
        • UserModData
        • UserOptions
        • UserPreviousName
        • UserReleaseYearStatistic
        • UserScoreStatistic
        • UserStaffStatistic
        • UserStartYearStatistic
        • UserStatistics
        • UserStatisticTypes
        • UserStats
        • UserStatusStatistic
        • UserStudioStatistic
        • UserTagStatistic
        • UserVoiceActorStatistic
        • YearStats
      • union
        • ActivityUnion Reference
        • LikeableUnion
        • NotificationUnion
Powered by GitBook
On this page
  • Page field limitations
  • PageInfo
  • Making a paginated query
  • Collections
  1. docs
  2. guide
  3. graphql

Pagination

Pagination in the AniList GraphQL API.

PreviousMutationsNextWhat's Next?

Last updated 7 months ago

You might have noticed that all the top level queries (, , , etc) return a single object. If you want to get multiple objects, you will need to use the top level query.

In most cases, you can simply wrap your query in a Page object with minimal other changes.

::: info Example If you want a page of characters, the normal query would be Character. To receive a paginated list of characters, you would wrap your Character query with Page and rename Character to characters. :::

Page field limitations

The schema for Page shows that it has many data fields available. ie: media, characters, staff, etc.

Only one of these fields can be used in a single Page query. This means that a single Page query cannot return paginated data for multiple types of data.

The pageInfo field is exempt from this rule.

::: tip Valid

The Page query only has one data field along with the optional pageInfo field.

{
  Page {
    pageInfo {
      hasNextPage
    }
    media {
      id
    }
  }
}

:::

The Page query has multiple data fields, but only one of them can be used in a single query.

{
  Page {
    pageInfo {
      hasNextPage
    }
    media {
      id
    }
    characters {
      id
    }
  }
}

:::

PageInfo

The Page query also provides the pageInfo field, which contains information about the current page and the total number of pages.

::: warning PageInfo Degredation Currently, the PageInfo object is limited in functionality due to performance issues. The total and lastPage fields are not currently accurate. You should only rely on hasNextPage for any pagination logic. :::

Making a paginated query

Let's write another query. This time, we'll make a basic search query to get a list of Media entries.

:::details Example Query Let's create a simple query to get an anime by it's unique ID.

::: code-group <<< @/guide/snippets/graphql/pagination/javascript.js{js:line-numbers} [Javascript] <<< @/guide/snippets/graphql/pagination/php.php{php:line-numbers} [PHP] <<< @/guide/snippets/graphql/pagination/python.py{py:line-numbers} [Python] <<< @/guide/snippets/graphql/pagination/rust.rs{rs:line-numbers} [Rust] :::

The request in the above example will return the following JSON response:

{
  "data": {
    "Page": {
      "pageInfo": {
        "currentPage": 1,
        "hasNextPage": true,
        "perPage": 3
      },
      "media": [
        {
          "id": 55191,
          "title": {
            "romaji": "Fate/Zero"
          }
        },
        {
          "id": 10087,
          "title": {
            "romaji": "Fate/Zero"
          }
        },
        {
          "id": 33649,
          "title": {
            "romaji": "Fate/Zero"
          }
        }
      ]
    }
  }
}

::: info Note how the query still uses the $id variable but we did not provide a value for it in the variables object. This is valid and the GraphQL server will simply ignore any variables that are not provided. This allows you to make more complex and flexible queries without the need to modify the query string directly. :::

::: tip For stronger type safety, you can define your variables in the query with a ! to indicate that they are required.

ie: ($id: Int!) :::

Collections

Some top level queries return collections of data. These collections are used when pagination does not make sense, but there is still a need to return a list of items.

Examples:

  • Returns a list of all genres in use on AniList.

  • Returns a list of all anime or manga entries on a user's list.

::: danger Invalid

❌
✔️
Media
Character
Staff
Page
Apollo Studio
GenreCollection
MediaListCollection