zendesk-api-cursor-pagination

Written by

eesel Team

Last edited 2 mars 2026

{
  "title": "Pagination par curseur de l'API Zendesk : un guide complet pour les développeurs",
  "slug": "zendesk-api-cursor-pagination",
  "locale": "fr",
  "date": "2026-03-02",
  "updated": "2026-03-02",
  "template": "default",
  "excerpt": "Un guide pratique pour implémenter la pagination par curseur dans l'API Zendesk, avec des exemples de code complets en Python et Node.js.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk API",
    "Cursor Pagination",
    "API Development",
    "Python",
    "Node.js"
  ],
  "readTime": 10,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Pagination par curseur de l'API Zendesk : un guide complet pour les développeurs",
    "description": "Un guide pratique pour implémenter la pagination par curseur dans l'API Zendesk, avec des exemples de code complets en Python et Node.js.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-ba8d4d5f-b15b-4a3c-b8ca-c91651e8e5b4"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-ba8d4d5f-b15b-4a3c-b8ca-c91651e8e5b4",
  "coverImageAlt": "Image de bannière pour la pagination par curseur de l'API Zendesk : un guide complet pour les développeurs",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Foire aux questions",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Quel est le nombre maximal d'enregistrements que je peux récupérer avec la pagination par curseur de l'API Zendesk ?",
        "answer": "Avec la pagination par curseur, il n'y a pas de limite stricte. Vous pouvez récupérer l'intégralité de votre base de données de tickets. Avec la pagination par décalage, vous êtes limité à 10 000 enregistrements (100 pages à 100 enregistrements par page)."
      },
      {
        "question": "Comment gérer les limites de débit lors de l'utilisation de la pagination par curseur de l'API Zendesk ?",
        "answer": "Surveillez les réponses HTTP 429 et respectez l'en-tête Retry-After. Implémentez un backoff exponentiel pour éviter d'atteindre la limite de débit de manière répétée. Attendez plus longtemps entre les nouvelles tentatives à chaque essai."
      },
      {
        "question": "La pagination par curseur est-elle disponible pour tous les points de terminaison de l'API Zendesk ?",
        "answer": "La plupart des points de terminaison de liste prennent en charge la pagination par curseur, y compris les tickets, les utilisateurs et les organisations. Consultez la documentation spécifique du point de terminaison pour confirmer. Si la pagination par curseur n'est pas mentionnée, le point de terminaison ne prend probablement en charge que la pagination par décalage."
      },
      {
        "question": "Puis-je obtenir le nombre total de tickets lors de l'utilisation de la pagination par curseur ?",
        "answer": "Les réponses de pagination par curseur n'incluent pas de nombre total. Vous pouvez effectuer un appel séparé à un point de terminaison de comptage (comme /api/v2/tickets/count.json) si vous avez besoin du nombre total d'enregistrements."
      },
      {
        "question": "La pagination par curseur de l'API Zendesk fonctionne-t-elle de la même manière pour les utilisateurs et les organisations ?",
        "answer": "Oui, la pagination par curseur et par décalage fonctionne de manière cohérente sur la plupart des points de terminaison de l'API Zendesk, y compris les utilisateurs, les organisations et les tickets. Le même paramètre page[size] active la pagination par curseur pour tous les points de terminaison pris en charge."
      },
      {
        "question": "Puis-je utiliser la pagination par curseur de l'API Zendesk avec l'API de recherche ?",
        "answer": "L'API de recherche standard utilise uniquement la pagination par décalage et renvoie un maximum de 1 000 résultats. Pour les ensembles de résultats plus volumineux, utilisez le point de terminaison Exporter les résultats de la recherche qui prend en charge la pagination par curseur."
      }
    ],
    "supportLink": null
  }
}
---

Si vous créez des intégrations avec [Zendesk](https://www.zendesk.com), vous découvrirez rapidement que l'API ne vous remet pas l'intégralité de votre base de données de tickets en une seule fois. Au lieu de cela, elle sert les données en morceaux par le biais d'un mécanisme appelé pagination. C'est voulu. La pagination maintient l'API réactive et empêche les délais d'attente lorsque vous traitez des milliers (voire des millions) de tickets de support.

Mais voici où cela devient intéressant. Zendesk offre deux façons différentes de paginer vos données : la pagination par curseur et la pagination par décalage. L'une est rapide, moderne et pratiquement illimitée. L'autre est limitée à 10 000 enregistrements et traîne des bagages provenant d'anciennes conceptions d'API. Depuis août 2023, Zendesk pousse les développeurs vers la pagination par curseur en imposant des limites strictes à la méthode de décalage.

Dans ce guide, nous allons passer en revue les deux approches de pagination avec des exemples de code fonctionnels. Vous apprendrez quand utiliser chaque méthode, comment gérer les cas extrêmes et quels pièges éviter. Et si vous pensez qu'il doit y avoir un moyen plus facile de travailler avec les données Zendesk sans écrire vous-même la logique de pagination, nous aborderons également ce point.

Pour plus de contexte sur les approches de pagination de Zendesk, vous pouvez également trouver notre [guide complet sur la pagination des tickets Zendesk](https://www.eesel.ai/en/blog/zendesk-api-list-tickets-pagination) utile.

![Organigramme de la pagination par curseur montrant la boucle requête-réponse pour la récupération de grands ensembles de données](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/27466055-272e-4c50-a929-5f3a0ca32c4b)

## Comprendre la pagination dans l'API Zendesk

Avant de plonger dans le code, clarifions pourquoi la pagination existe et comment elle fonctionne à un niveau élevé.

L'API Zendesk divise les grands ensembles de résultats en pages plus petites pour des raisons de performance. Demander 100 000 tickets en un seul appel API entraînerait un délai d'attente ou un plantage de la plupart des systèmes. Au lieu de cela, vous demandez la page 1, traitez ces résultats, puis demandez la page 2, et ainsi de suite jusqu'à ce que vous ayez tout récupéré.

Différents points de terminaison ont des tailles de page par défaut différentes :

- **Tickets et utilisateurs** : 100 éléments par page
- **Articles du centre d'aide** : 30 éléments par page
- **Résultats de recherche** : 100 éléments par page maximum

Vous pouvez généralement ajuster la taille de la page dans certaines limites, mais vous ne pouvez pas dépasser le maximum pour un point de terminaison donné.

Toutes les requêtes API sont comptabilisées dans votre limite de débit. Zendesk autorise un certain nombre de requêtes par minute en fonction de votre plan, et la pagination peut entamer ce quota rapidement si vous récupérez de grands ensembles de données. La bonne nouvelle est que la pagination par curseur est plus efficace que la pagination par décalage, de sorte que le changement de méthode peut en fait réduire votre utilisation de l'API.

Un changement essentiel à connaître : à partir du 15 août 2023, les requêtes de pagination basées sur le décalage au-delà des 10 000 premiers enregistrements (100 pages) renvoient une erreur 400 Bad Request. Si vous avez besoin de plus de 10 000 enregistrements, la pagination par curseur est désormais votre seule option. Pour en savoir plus sur ce changement, consultez l'[annonce de la pagination par décalage de Zendesk](https://support.zendesk.com/hc/en-us/articles/5591904358938).

## Pagination par curseur contre pagination par décalage

Décomposons les différences entre ces deux approches afin que vous puissiez choisir la bonne pour votre cas d'utilisation.

| Fonctionnalité | Pagination par curseur | Pagination par décalage |
|---------|------------------|-------------------|
| Limite d'enregistrements | Illimité | 10 000 maximum |
| Performance | Cohérente (rapide même sur les pages profondes) | Se dégrade à mesure que le numéro de page augmente |
| Nombre total disponible | Non | Oui (propriété count) |
| Aller à une page arbitraire | Impossible | Possible |
| Cohérence des données pendant la pagination | Meilleure | Sujet aux doublons/enregistrements manqués |
| Recommandation Zendesk | Recommandée | Support hérité uniquement |

**Utilisez la pagination par curseur lorsque :**

- Vous avez besoin de plus de 10 000 enregistrements
- La performance est importante (surtout pour les grands ensembles de données)
- Vous traitez les données séquentiellement sans avoir besoin de sauter

**Utilisez la pagination par décalage lorsque :**

- Vous avez besoin du nombre total d'enregistrements
- Vous créez une interface utilisateur qui permet aux utilisateurs d'aller à des pages spécifiques
- Vous travaillez avec un petit ensemble de données (moins de 10 000 enregistrements) et la simplicité est importante

Si vous utilisez actuellement la pagination par décalage et que vous atteignez la limite de 10 000 enregistrements, la migration vers la pagination par curseur est simple. Les principaux changements sont les suivants :

1. Remplacez le paramètre `page` par `page[size]`
2. Vérifiez `meta.has_more` au lieu de vérifier si `next_page` est nul
3. Utilisez `links.next` pour l'URL de la page suivante au lieu de `next_page`

Chez [eesel AI](https://www.eesel.ai), nous nous intégrons directement à [Zendesk](https://www.eesel.ai/integration/zendesk-ai) et gérons automatiquement toute la complexité de la pagination. Mais si vous créez des intégrations personnalisées, il est essentiel de comprendre ces différences.

## Comment fonctionne la pagination par curseur

La pagination par curseur utilise un pointeur (le curseur) qui suit votre position dans l'ensemble de données plutôt que de compter les enregistrements depuis le début à chaque fois. Cela la rend considérablement plus rapide pour les grands ensembles de données, car l'API n'a pas besoin de compter et de sauter des enregistrements pour trouver votre page.

Pour activer la pagination par curseur, ajoutez un paramètre `page[size]` à votre requête. Cela indique à Zendesk que vous voulez utiliser le mode curseur et spécifie le nombre d'éléments à renvoyer par page (jusqu'à 100 pour la plupart des points de terminaison). Consultez la [documentation de la pagination par curseur de Zendesk](https://developer.zendesk.com/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination/) pour tous les détails.

La réponse comprend deux objets clés :

- **meta** : Contient `has_more` (booléen), `after_cursor` et `before_cursor`
- **links** : Contient les URL `next` et `prev` pour les pages adjacentes

Voici à quoi ressemble une réponse typique :

```json
{
  "tickets": [
    { "id": 1, "subject": "Sample ticket" },
    { "id": 2, "subject": "Another ticket" }
  ],
  "meta": {
    "has_more": true,
    "after_cursor": "eyJvIjoibmljZV9pZCIsInYiOiJhV2tCQUFBQUFBQUEifQ==",
    "before_cursor": "eyJvIjoibmljZV9pZCIsInYiOiJhUzRCQUFBQUFBQUEifQ=="
  },
  "links": {
    "next": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=eyJvIjoibmljZV9pZCIsInYiOiJhV2tCQUFBQUFBQUEifQ==",
    "prev": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[before]=eyJvIjoibmljZV9pZCIsInYiOiJhUzRCQUFBQUFBQUEifQ=="
  }
}

Vous continuez à paginer jusqu'à ce que meta.has_more soit faux. À ce stade, vous avez récupéré tous les enregistrements.

Implémentation de la pagination par curseur en Python

Voici un exemple de travail complet utilisant Python et la bibliothèque requests :

import requests
import time

ZENDESK_SUBDOMAIN = 'your-subdomain'
ZENDESK_EMAIL = 'your-email@example.com'
ZENDESK_API_TOKEN = 'your-api-token'

BASE_URL = f'https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json'
auth = (f'{ZENDESK_EMAIL}/token', ZENDESK_API_TOKEN)

def fetch_all_tickets():
    tickets = []
    url = BASE_URL
    params = {'page[size]': 100}  # Use cursor pagination with 100 items per page

    while url:
        response = requests.get(url, auth=auth, params=params)

        # Handle rate limiting
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f'Rate limited. Waiting {retry_after} seconds...')
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        data = response.json()

        # Process tickets from this page
        for ticket in data['tickets']:
            tickets.append(ticket)
            print(f"Fetched ticket {ticket['id']}: {ticket['subject']}")

        # Check if there are more pages
        if data['meta']['has_more']:
            url = data['links']['next']
            params = None  # Next URL already includes all parameters
        else:
            url = None

    return tickets

if __name__ == '__main__':
    all_tickets = fetch_all_tickets()
    print(f'\nTotal tickets fetched: {len(all_tickets)}')

Points clés à noter dans cet exemple :

Nous commençons par page[size]=100 pour activer la pagination par curseur
Nous vérifions la limitation de débit (HTTP 429) et respectons l'en-tête Retry-After
Après la première requête, nous utilisons directement l'URL links.next pour les pages suivantes
La boucle continue jusqu'à ce que has_more soit faux

Implémentation de la pagination par curseur dans Node.js

Voici la même logique dans Node.js en utilisant axios :

const axios = require('axios');

const ZENDESK_SUBDOMAIN = 'your-subdomain';
const ZENDESK_EMAIL = 'your-email@example.com';
const ZENDESK_API_TOKEN = 'your-api-token';

const BASE_URL = `https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json`;
const auth = Buffer.from(`${ZENDESK_EMAIL}/token:${ZENDESK_API_TOKEN}`).toString('base64');

async function fetchAllTickets() {
  const tickets = [];
  let url = BASE_URL;
  let params = { 'page[size]': 100 };

  try {
    do {
      const response = await axios.get(url, {
        headers: { Authorization: `Basic ${auth}` },
        params: params
      });

      const data = response.data;

      // Process tickets from this page
      for (const ticket of data.tickets) {
        tickets.push(ticket);
        console.log(`Fetched ticket ${ticket.id}: ${ticket.subject}`);
      }

      // Prepare for next page
      if (data.meta.has_more) {
        url = data.links.next;
        params = null; // Next URL includes all parameters
      } else {
        url = null;
      }

    } while (url);

    console.log(`\nTotal tickets fetched: ${tickets.length}`);
    return tickets;

  } catch (error) {
    if (error.response && error.response.status === 429) {
      const retryAfter = error.response.headers['retry-after'] || 60;
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
    } else {
      console.error('Error fetching tickets:', error.message);
    }
    throw error;
  }
}

fetchAllTickets();

Pièges courants et comment les éviter

Même avec un code fonctionnel, vous rencontrerez des cas extrêmes en production. Voici comment gérer les problèmes les plus courants.

Gestion des limites de débit

Zendesk renvoie HTTP 429 lorsque vous dépassez votre limite de débit. La réponse comprend un en-tête Retry-After vous indiquant combien de secondes attendre. Implémentez toujours un backoff exponentiel plutôt que de marteler l'API :

import time

def make_request_with_backoff(url, auth, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, auth=auth)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            # Exponential backoff: wait longer with each retry
            wait_time = retry_after * (2 ** attempt)
            time.sleep(wait_time)
            continue

        return response

    raise Exception('Max retries exceeded')

Gérer les pages vides

De temps en temps, vous pouvez rencontrer une page vide où has_more était vrai, mais la requête suivante ne renvoie aucun enregistrement. Cela peut se produire lorsque le dernier enregistrement de la page précédente était le dernier enregistrement de l'ensemble de données entier. Enregistrez la valeur after_cursor précédente pour une utilisation future dans ce cas.

Expiration du curseur

Pour le point de terminaison Exporter les résultats de la recherche, les curseurs expirent après une heure. Si votre traitement prend plus de temps, vous devrez redémarrer l'exportation ou traiter les données plus rapidement.

Limitations de l'API de recherche

L'API de recherche a ses propres particularités de pagination :

Maximum 1 000 résultats par requête au total
Maximum 100 résultats par page
Utilise uniquement la pagination par décalage
Demander la page 11 (à 100 résultats par page) renvoie une erreur 422

Si vous avez besoin de plus de 1 000 résultats de recherche, utilisez plutôt le point de terminaison Exporter les résultats de la recherche, qui prend en charge la pagination par curseur et renvoie jusqu'à 1 000 enregistrements par page. Consultez la documentation de l'API de recherche de Zendesk pour plus de détails.

Cohérence des données pendant la pagination

Les données paginées peuvent être inexactes en raison de la nature en temps réel des données. Un ou plusieurs éléments peuvent être ajoutés ou supprimés de votre instance de base de données entre les requêtes. Une façon de réduire les inexactitudes de la pagination (sans toutefois les éliminer complètement) est de trier les enregistrements par un attribut qui ne peut pas être modifié, tel que l'identifiant ou la date de création, si cela est pris en charge par la ressource.

Chez eesel AI, notre agent IA gère automatiquement ces complexités. Nous gérons la limitation de débit, l'expiration du curseur et les problèmes de cohérence des données afin que vous n'ayez pas à écrire cette logique vous-même.

Migration de la pagination par décalage vers la pagination par curseur

Si vous utilisez actuellement la pagination par décalage, voici un guide de migration rapide montrant les principaux changements :

Avant (pagination par décalage) :

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
while url:
    response = requests.get(url, auth=auth)
    data = response.json()
    # Process tickets...
    url = data['next_page']  # null when done

Après (pagination par curseur) :

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json?page[size]=100'
params = {'page[size]': 100}
while url:
    response = requests.get(url, auth=auth, params=params)
    data = response.json()
    # Process tickets...
    if data['meta']['has_more']:
        url = data['links']['next']
        params = None
    else:
        url = None

Les principaux changements sont les suivants :

Ajoutez le paramètre page[size] pour activer le mode curseur
Vérifiez meta.has_more au lieu de vérifier si next_page est nul
Utilisez links.next pour l'URL de la page suivante au lieu de next_page
Supprimez la dépendance à la propriété count (non disponible dans la pagination par curseur)

Évitez la complexité de la pagination avec eesel AI

La création d'intégrations API personnalisées avec une pagination, une gestion des erreurs et une limitation de débit appropriées demande un effort de développement important. Vous devez écrire le code, le maintenir à mesure que Zendesk met à jour son API et gérer tous les cas extrêmes dont nous avons parlé.

Pour de nombreuses équipes, il existe un chemin plus simple. eesel AI se connecte directement à votre compte Zendesk et gère automatiquement toute la récupération des données. Au lieu d'écrire la logique de pagination, vous configurez ce que vous voulez accomplir grâce à une interface visuelle.

Voici comment cela fonctionne :

Connectez eesel AI à votre compte Zendesk en quelques minutes
L'IA apprend de vos tickets passés, des articles du centre d'aide et des macros
Vous définissez des règles d'automatisation en langage clair (aucun code requis)
eesel AI gère tous les appels API, la pagination et le traitement des données

Vous pouvez automatiser le routage des tickets, rédiger des réponses pour vos agents, étiqueter et prioriser les tickets entrants et générer des rapports. Le tout sans écrire une seule ligne de code de pagination.

Pour les équipes qui ont besoin d'intégrations personnalisées, l'API Zendesk reste le bon choix. Mais si votre objectif est d'automatiser les flux de travail et d'améliorer l'efficacité, des outils comme eesel AI peuvent vous y amener plus rapidement. Consultez nos tarifs pour voir comment nous nous comparons à la création et à la maintenance de solutions personnalisées.

Page de tarification d'eesel AI montrant des coûts publics transparents

Partager cet article

Article by

zendesk-api-cursor-pagination

Implémentation de la pagination par curseur en Python

Implémentation de la pagination par curseur dans Node.js

Pièges courants et comment les éviter

Gestion des limites de débit

Gérer les pages vides

Expiration du curseur

Limitations de l'API de recherche

Cohérence des données pendant la pagination

Migration de la pagination par décalage vers la pagination par curseur

Évitez la complexité de la pagination avec eesel AI

Agents IA et chatbots pour l'assistance

eesel Team

Lire d'autres articles

zendesk-web-widget-offline-form

zendesk-web-widget-embed-code

zendesk-view-sla-column

Commencez maintenant
gratuitement.

zendesk-api-cursor-pagination

Implémentation de la pagination par curseur en Python

Implémentation de la pagination par curseur dans Node.js

Pièges courants et comment les éviter

Gestion des limites de débit

Gérer les pages vides

Expiration du curseur

Limitations de l'API de recherche

Cohérence des données pendant la pagination

Migration de la pagination par décalage vers la pagination par curseur

Évitez la complexité de la pagination avec eesel AI

Agents IA et chatbots pour l'assistance

eesel Team

Lire d'autres articles

zendesk-web-widget-offline-form

zendesk-web-widget-embed-code

zendesk-view-sla-column

Commencez maintenant gratuitement.

Commencez maintenant
gratuitement.