> ## Documentation Index > Fetch the complete documentation index at: https://www.pickfu.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List surveys > Returns a paginated list of surveys with filtering and sorting options. Use query parameters to filter by status, type, country, tags, projects, and more. ## OpenAPI ````yaml /api-reference/openapi.json get /surveys openapi: 3.1.0 info: title: PickFu API version: 1.0.0 description: >- The PickFu API enables programmatic access to create surveys, retrieve results, and integrate PickFu into your workflows. ## Overview PickFu helps you get instant consumer feedback through surveys. With the API, you can: - Create surveys programmatically - Retrieve survey results and respondent data - Target specific audiences with demographic traits - Integrate PickFu into your product development workflow ## Rate Limits Selected endpoints (currently the CSV export endpoints) enforce per-caller rate limits and return `429 Too Many Requests` when exceeded. See each endpoint description for its specific budget. ## Authentication All API requests require a Bearer token — either an API key or an OAuth 2.0 access token. See the [Authentication guide](https://www.pickfu.com/docs/developers/authentication) for details. contact: name: PickFu Support email: support@pickfu.com url: https://www.pickfu.com servers: - url: https://api.pickfu.com/v1 description: Production - url: https://api.pickfu-sandbox.com/v1 description: Sandbox security: - bearerAuth: [] tags: - name: Surveys description: >- Create, retrieve, update, and publish surveys. Surveys are the core resource — each contains one or more questions with answer options. - name: Responses description: >- Retrieve individual responses (answers) for a survey, with pagination and per-question filtering. - name: Tags description: Organize surveys with tags. Tags are scoped to your team/account. - name: Projects description: >- Organize surveys into projects. Projects group related surveys and can be bookmarked or archived. - name: Traits description: >- Audience targeting and reporting traits used to reach specific demographics and segment survey results. - name: Playbooks description: >- Discover and retrieve step-by-step research playbooks. Each playbook is a structured sequence of polls designed for a specific research goal. - name: Help description: Search the PickFu help center for articles and guides. - name: Media description: >- Generate images from text prompts and upload media files to the PickFu CDN. paths: /surveys: get: tags: - Surveys summary: List surveys description: >- Returns a paginated list of surveys with filtering and sorting options. Use query parameters to filter by status, type, country, tags, projects, and more. operationId: listSurveys parameters: - schema: type: integer minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: integer minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Results per page (1-100) - schema: type: string in: query name: status required: false description: >- Filter by survey status. Comma-separated values: completed, in-progress, unpublished, archived - schema: type: string in: query name: type required: false description: >- Filter by question type. Comma-separated values: head_to_head, ranked, open_ended, click_test, etc. - schema: type: string in: query name: option_type required: false description: Filter by option type (e.g. text, image). Comma-separated. - schema: type: string in: query name: countries required: false description: Filter by country codes. Comma-separated (e.g. US,GB,CA). - schema: type: string in: query name: tags required: false description: >- Filter by tag IDs — opaque identifiers (tag_<32-hex>) and/or legacy integers, mixed freely. Comma-separated. - schema: type: string in: query name: audiences required: false description: Filter by audience IDs. Comma-separated. - schema: type: string maxLength: 255 in: query name: text required: false description: Full-text search across survey names and questions - schema: type: string in: query name: member_id required: false description: >- Filter by team member ID(s) — opaque identifiers (usr_<32-hex>, as returned by GET /users) and/or legacy integers, mixed freely. Comma-separated. - schema: type: string in: query name: project_ids required: false description: Filter by project GUIDs or numeric IDs. Comma-separated. - schema: type: string format: date-time in: query name: published_after required: false description: Only include surveys published after this ISO 8601 datetime - schema: type: string enum: - createdAt - name - creator - status default: createdAt in: query name: sort_by required: false description: Field to sort by - schema: type: string enum: - asc - desc default: desc in: query name: dir required: false description: Sort direction responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array description: List of surveys items: type: object properties: id: type: string description: Survey GUID name: type: string description: Survey name url: type: string description: URL to view survey results status: type: string description: >- Survey status: completed, in-progress, unpublished, or archived type: type: string description: Primary question type countryCode: type: string nullable: true description: Two-letter country code sampleSize: type: number nullable: true description: Number of respondents requested numResponses: type: number description: Number of responses collected createdAt: type: string nullable: true description: Creation timestamp (ISO 8601) publishedAt: type: string nullable: true description: Publication timestamp (ISO 8601) completedAt: type: string nullable: true description: Completion timestamp (ISO 8601) creatorName: type: string nullable: true description: Name of the team member who created the survey targeting: type: array items: type: string description: Targeting trait permalinks tags: type: array description: Tags associated with the survey items: type: object required: - id - name properties: id: type: string description: Opaque tag identifier (tag_<32-hex>) name: type: string description: Tag name projects: type: array description: Projects the survey belongs to items: type: object required: - id - name properties: id: type: string description: Project GUID name: type: string description: Project name elements: type: array description: Questions in this survey (summary view) items: type: object properties: id: type: string description: Question GUID question: type: string nullable: true description: Question text subtype: type: string description: Question subtype variant: type: string nullable: true description: Question variant position: type: number description: Display position pagination: type: object description: Pagination metadata properties: page: type: number description: Current page number limit: type: number description: Results per page total: type: number description: Total number of results totalPages: type: number description: Total number of pages components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- OAuth2 access token obtained via the authorization flow. Include in the Authorization header as: `Bearer {access_token}` ````