> ## Documentation Index > Fetch the complete documentation index at: https://docs.gravitypay.app/llms.txt > Use this file to discover all available pages before exploring further. # Listar alunos > Lista paginada dos alunos da loja da chave, cada um com todas as matrículas. Os filtros de matrícula (`courseId`, `cohortId`, `enrollmentStatus`) devolvem os alunos com ao menos uma matrícula que casa com todos eles, e `enrollments` continua com todas as matrículas. O aluno de pré-visualização do seller nunca aparece. Ordem: `createdAt` decrescente e, no empate, `id` decrescente. As matrículas de `enrollments` vêm por `createdAt` crescente e, no empate, `id` crescente. Escopo exigido: `students:read`. ## OpenAPI ````yaml /openapi.json get /v1/students openapi: 3.1.0 info: title: Gravity Play API version: 1.0.0 description: >- API para criar cobranças, receber pagamentos e ler cursos, turmas, alunos e progresso da área de membros. Cada chave de API tem escopos; cada operação indica o escopo que exige. servers: - url: https://api.sandbox.gravitypay.app description: Sandbox (testes) — alvo do try-it - url: https://api.gravitypay.app description: Produção security: - bearerAuth: [] tags: - name: Cobranças description: Cobranças avulsas com link de pagamento. - name: Pagamentos description: Vendas da loja e vendedores. - name: Assinaturas description: Assinaturas da loja, com dados do cliente. Exige `subscriptions:read`. - name: Cursos description: Cursos da área de membros, com módulos e aulas. - name: Turmas description: Turmas dos cursos. - name: Alunos description: 'Alunos, matrículas e progresso. Dado pessoal: exige `students:read`.' paths: /v1/students: get: tags: - Alunos summary: Listar alunos description: >- Lista paginada dos alunos da loja da chave, cada um com todas as matrículas. Os filtros de matrícula (`courseId`, `cohortId`, `enrollmentStatus`) devolvem os alunos com ao menos uma matrícula que casa com todos eles, e `enrollments` continua com todas as matrículas. O aluno de pré-visualização do seller nunca aparece. Ordem: `createdAt` decrescente e, no empate, `id` decrescente. As matrículas de `enrollments` vêm por `createdAt` crescente e, no empate, `id` crescente. Escopo exigido: `students:read`. operationId: listStudents parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - name: email in: query required: false schema: type: string description: Devolve só o aluno com este e-mail, sem diferenciar maiúsculas. - name: courseId in: query required: false schema: type: string description: Alunos com matrícula neste curso. Curso de outra loja responde 400. - name: cohortId in: query required: false schema: type: string description: Alunos com matrícula nesta turma. Turma de outra loja responde 400. - name: enrollmentStatus in: query required: false schema: type: string enum: - ACTIVE - REVOKED description: Alunos com matrícula neste status. responses: '200': description: Lista de alunos content: application/json: schema: $ref: '#/components/schemas/StudentList' example: object: list data: - id: clx1student01 object: student name: Maria Souza email: maria@example.com avatarUrl: null lastLoginAt: '2026-09-10T08:00:00.000Z' createdAt: '2026-06-11T14:20:00.000Z' enrollments: - id: clx1enroll001 object: enrollment status: ACTIVE hasAccess: true source: PURCHASE course: id: clx1course0001 title: Formação em NR-35 productId: clx1product001 cohort: id: clx1cohort002 name: Mentoria isDefault: false grantedAt: '2026-06-11T14:21:00.000Z' expiresAt: null revokedAt: null revokeReason: null guaranteeEndsAt: '2026-06-18T14:21:00.000Z' paymentId: clx1payment01 subscriptionId: null createdAt: '2026-06-11T14:21:00.000Z' page: 1 perPage: 50 total: 1 totalPages: 1 hasMore: false '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/InsufficientScope' components: parameters: Page: name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: >- Página (começa em 1). Página além da última devolve `data` vazio e `hasMore` false. PerPage: name: perPage in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Itens por página (1 a 100; default 50). schemas: StudentList: type: object required: - object - data - page - perPage - total - totalPages - hasMore properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/StudentWithEnrollments' page: type: integer perPage: type: integer total: type: integer totalPages: type: integer hasMore: type: boolean StudentWithEnrollments: description: >- Aluno com todas as matrículas, como sai em GET /v1/students e GET /v1/students/{id}. allOf: - $ref: '#/components/schemas/Student' - type: object required: - enrollments properties: enrollments: type: array items: $ref: '#/components/schemas/Enrollment' Error: type: object properties: error: type: object required: - type - message properties: type: type: string description: >- `authentication` (401), `insufficient_scope` (403), `invalid_request` (400) ou `not_found` (404). message: type: string param: type: string description: Parâmetro que falhou, em `invalid_request`. requiredScope: type: string description: Escopo que falta, em `insufficient_scope`. Student: type: object description: Aluno da loja. Nunca traz senha, bloqueio de login nem dispositivos. required: - id - object - name - email - avatarUrl - lastLoginAt - createdAt properties: id: type: string object: type: string enum: - student name: type: - string - 'null' email: type: string avatarUrl: type: - string - 'null' lastLoginAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time Enrollment: type: object required: - id - object - status - hasAccess - source - course - cohort - grantedAt - expiresAt - revokedAt - revokeReason - guaranteeEndsAt - paymentId - subscriptionId - createdAt properties: id: type: string object: type: string enum: - enrollment status: type: string enum: - ACTIVE - REVOKED hasAccess: type: boolean description: true quando a matrícula está ACTIVE e expiresAt é nulo ou futuro. source: type: string enum: - PURCHASE - MANUAL course: type: object required: - id - title - productId properties: id: type: string title: type: string productId: type: string cohort: type: object description: Turma da matrícula, sempre preenchida. required: - id - name - isDefault properties: id: type: string name: type: string isDefault: type: boolean grantedAt: type: string format: date-time expiresAt: type: - string - 'null' format: date-time revokedAt: type: - string - 'null' format: date-time revokeReason: type: - string - 'null' enum: - REFUND - CHARGEBACK - SUBSCRIPTION_ENDED - SELLER - null guaranteeEndsAt: type: - string - 'null' format: date-time description: Fim da trava de garantia. null em matrícula sem trava. paymentId: type: - string - 'null' subscriptionId: type: - string - 'null' createdAt: type: string format: date-time responses: Error: description: Erro content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientScope: description: A chave é válida, mas não tem o escopo exigido pela operação. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: insufficient_scope message: Esta chave de API não tem o escopo students:read. requiredScope: students:read securitySchemes: bearerAuth: type: http scheme: bearer ````