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

# Execute a view

> Executes a shared view and returns paginated results. The view's filters,
sorting, and column configuration are applied automatically.

This is the recommended way to pull structured data from item — configure
the view in the UI with the exact filters you need, then call this endpoint
on a schedule.




## OpenAPI

````yaml /openapi.yaml get /api/objects/{objectType}/views/{viewId}
openapi: 3.1.0
info:
  title: item API
  description: >
    The item API provides full CRUD access to your organization's data — People,
    Companies, and Custom Objects.


    Use it to:

    - Push structured data into item on a schedule

    - Sync custom field values across your stack

    - Pull filtered records and pre-configured views

    - Use item as your source of truth for customer data


    ## Authentication


    All requests require an API key passed in the `x-api-key` header.


    You can generate an API key from **Settings > System > API Key** in your
    item workspace.


    ```bash

    curl -H "x-api-key: sk_live_..." https://app.useitem.io/api/objects/contacts

    ```
  version: 1.0.0
  contact:
    name: item Support
servers:
  - url: https://app.useitem.io
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - apiKey: []
tags:
  - name: Objects
    description: Create, read, update, and delete People, Companies, and Custom Objects.
  - name: Schema
    description: Discover available object types and their field definitions.
  - name: Users
    description: List organization members and their access levels.
  - name: Views
    description: List and execute pre-configured views to pull filtered data.
  - name: Batch
    description: Bulk create or update objects for high-frequency sync operations.
  - name: Webhooks
    description: Trigger skills (AI agents) via HTTP webhooks from external systems.
paths:
  /api/objects/{objectType}/views/{viewId}:
    parameters:
      - $ref: '#/components/parameters/objectType'
      - name: viewId
        in: path
        required: true
        description: >-
          The view ID (UUID) from the [List
          Views](#tag/Views/operation/listViews) endpoint.
        schema:
          type: string
          format: uuid
    get:
      tags:
        - Views
      summary: Execute a view
      description: >
        Executes a shared view and returns paginated results. The view's
        filters,

        sorting, and column configuration are applied automatically.


        This is the recommended way to pull structured data from item —
        configure

        the view in the UI with the exact filters you need, then call this
        endpoint

        on a schedule.
      operationId: executeView
      parameters:
        - name: limit
          in: query
          description: 'Maximum records to return. Default: 50, max: 200.'
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: offset
          in: query
          description: Number of records to skip for pagination.
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: View results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ObjectRecord'
                  view:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: View not found or not shared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    objectType:
      name: objectType
      in: path
      required: true
      description: >
        The object type slug. Use `contacts` for People, `companies` for
        Companies,

        or the slug of a Custom Object (e.g., `deals`, `tickets`).


        Singular forms (`contact`, `company`) are also accepted.
      schema:
        type: string
      examples:
        contacts:
          value: contacts
          summary: People
        companies:
          value: companies
          summary: Companies
        custom:
          value: deals
          summary: Custom object
  schemas:
    ObjectRecord:
      type: object
      description: >
        A flat object containing all fields. System fields (name, email, phone,
        etc.) and

        custom fields are merged into a single level — the `custom_fields` JSON
        column is

        flattened so every field is a top-level key.
      properties:
        id:
          type: integer
          description: Unique record ID
          example: 123
        name:
          type: string
          example: Alex Johnson
        email:
          type: string
          example: alex@acme.com
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      additionalProperties: true
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total number of records matching the query
          example: 150
        limit:
          type: integer
          description: Maximum records returned per page
          example: 50
        offset:
          type: integer
          description: Number of records skipped
          example: 0
        has_more:
          type: boolean
          description: Whether more records exist beyond this page
          example: true
    Error:
      type: object
      properties:
        error:
          type: string
          example: Object not found
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your organization's API key (starts with `sk_live_`)

````