> ## Documentation Index > Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt > Use this file to discover all available pages before exploring further. # List a list's rows > One page of a list's rows: people in a people list, companies in a company list, as `type` says. A row's `columnValues` holds the values of the list's own columns, by column id. For the next page, send the page's `pagination.nextCursor` as `cursor`. Later pages keep the first page's `pageSize`; only a missing `nextCursor` marks the end. Send the same `filters` and sort with it. `filters` narrows the rows: a JSON object in which a row must match every key, and any of a key's values. Text keys take an array of values or `{"include": [...], "exclude": [...]}`: `name`, `title`, `dept`, `level`, `industryName`, `country`, `state`, `personalLocation`, `companyName`, `companyIndustry`, `companyHeadQuartersCountry`, `companyLocation`, `website`, `campaignEngagement` and `otherLists` (the names of other lists). `numberOfEmployees` takes ranges written as strings, such as `"51-200"` or `"10001+"`, and `revenue` a number. `keywords` (a job title, with `*` and `?` as wildcards) and `linkedinUrl` take one string. `enrichedEmail` (`enriched`, `not_enriched`, `no_emails_found`), `enrichedPhone` (`enriched`, `not_enriched`) and `emailValidity` (`valid`, `invalid`, `catch-all`, `unknown`, `do_not_mail`, `personal`, `unverified`) take `{"include": [...]}` or `{"exclude": [...]}`. `icpMatch` takes `["yes"]` or `["no"]`. `customColumns` maps a column id to `{"dataType": "string", "include": [...]}`, `{"dataType": "boolean", "value": true}` or `{"dataType": "number", "rangeMin": 1, "rangeMax": 10}`. Company lists take `companyName`, `companyIndustry`, `companyHeadQuartersCountry`, `website`, `numberOfEmployees`, `campaignEngagement` and `customColumns`. Values for `level`, `dept`, `industryName` and `country` are the people search's own, from `GET /v1/people/filters`, and `website` is a bare domain. A key the list kind does not take, or a value of the wrong shape, answers `422` `invalid_row_filters`; a value no row has matches nothing. Free. **Scope:** lists. Read-only keys may call it. ## OpenAPI ````yaml /openapi.json get /v1/lists/{listId}/rows openapi: 3.1.0 info: title: outbound.dev API version: v1 description: Find people and companies, and see what every call costs, with one API key. servers: - url: https://api.outbound.dev security: [] tags: - name: People description: >- Search people with filters, a saved search or a plain-language query, count matches and look up filter values. - name: Companies description: >- Search companies, count matches, name one company by its name, domain or LinkedIn page, and list its people. - name: Saved searches description: Keep a search under a title and run it again, for people or for companies. - name: Lists description: >- Keep people or companies in lists: create and change lists, page through their rows, and add or remove people. - name: Folders description: Group lists of one kind into folders. - name: Jobs description: >- Long tasks a call started: their progress, what they produced and what they were charged. - name: Account description: >- The calling key and its organization, its rate limits, and revoking the key. - name: Billing description: The balance, the ledger of every change to it, and the price list. - name: Usage and requests description: >- Calls and spend by day, and the record of every request of the last 30 days. paths: /v1/lists/{listId}/rows: get: tags: - Lists summary: List a list's rows description: >- One page of a list's rows: people in a people list, companies in a company list, as `type` says. A row's `columnValues` holds the values of the list's own columns, by column id. For the next page, send the page's `pagination.nextCursor` as `cursor`. Later pages keep the first page's `pageSize`; only a missing `nextCursor` marks the end. Send the same `filters` and sort with it. `filters` narrows the rows: a JSON object in which a row must match every key, and any of a key's values. Text keys take an array of values or `{"include": [...], "exclude": [...]}`: `name`, `title`, `dept`, `level`, `industryName`, `country`, `state`, `personalLocation`, `companyName`, `companyIndustry`, `companyHeadQuartersCountry`, `companyLocation`, `website`, `campaignEngagement` and `otherLists` (the names of other lists). `numberOfEmployees` takes ranges written as strings, such as `"51-200"` or `"10001+"`, and `revenue` a number. `keywords` (a job title, with `*` and `?` as wildcards) and `linkedinUrl` take one string. `enrichedEmail` (`enriched`, `not_enriched`, `no_emails_found`), `enrichedPhone` (`enriched`, `not_enriched`) and `emailValidity` (`valid`, `invalid`, `catch-all`, `unknown`, `do_not_mail`, `personal`, `unverified`) take `{"include": [...]}` or `{"exclude": [...]}`. `icpMatch` takes `["yes"]` or `["no"]`. `customColumns` maps a column id to `{"dataType": "string", "include": [...]}`, `{"dataType": "boolean", "value": true}` or `{"dataType": "number", "rangeMin": 1, "rangeMax": 10}`. Company lists take `companyName`, `companyIndustry`, `companyHeadQuartersCountry`, `website`, `numberOfEmployees`, `campaignEngagement` and `customColumns`. Values for `level`, `dept`, `industryName` and `country` are the people search's own, from `GET /v1/people/filters`, and `website` is a bare domain. A key the list kind does not take, or a value of the wrong shape, answers `422` `invalid_row_filters`; a value no row has matches nothing. Free. **Scope:** lists. Read-only keys may call it. operationId: getListsListIdRows parameters: - name: listId in: path required: true description: The list's id. schema: type: string minLength: 24 maxLength: 24 pattern: ^[0-9a-fA-F]+$ - name: pageSize in: query required: false description: Rows per page. schema: type: integer default: 100 minimum: 1 maximum: 1000 - name: cursor in: query required: false description: >- The `pagination.nextCursor` of the page before. Later pages keep the first page's size. schema: type: string minLength: 1 maxLength: 200 - name: sortBy in: query required: false description: >- The field to sort by. People lists: `firstName`, `lastName`, `jobTitle`, `createdAt`, `address.city`, `address.country`, a company field such as `company.name` or `company.linkedInHeadCount`, or `customColumns_`. Company lists: `name`, `domain`, `industry`, `revenue`, `linkedInHeadCount` or `customColumns_`. A field it does not know keeps the list's own order. schema: type: string minLength: 1 maxLength: 100 - name: sortOrder in: query required: false description: The order `sortBy` sorts in. schema: type: string enum: - asc - desc default: asc - name: filters in: query required: false description: >- Only the rows that match: a JSON object of row filters, at most 8,000 characters, in the keys this route describes. schema: type: string maxLength: 8000 example: >- {"companyName":["northwind"],"enrichedEmail":{"include":["enriched"]}} responses: '200': description: One page of the list's rows. headers: X-Request-Id: $ref: '#/components/headers/RequestId' X-Charged-Usd: $ref: '#/components/headers/ChargedUsd' X-Balance-Usd: $ref: '#/components/headers/BalanceUsd' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: type: object required: - type - data - pagination properties: type: type: string enum: - people - company description: 'What the rows are: `people` or `company`.' data: type: array items: type: object description: >- A person in a people list, a company in a company list. A field without a value is absent. required: - id properties: id: type: string description: >- The row's id. In a people list, the person's id, as `personIds` takes it. firstName: type: string description: People rows. lastName: type: string description: People rows. linkedinUrl: type: string description: >- People rows: the LinkedIn profile, as a full https URL. profilePictureUrl: type: string description: >- People rows: a public https link to the profile picture. jobTitle: type: string description: People rows. companyName: type: string description: 'People rows: the employer''s name.' companyDomain: type: string description: 'People rows: the employer''s domain.' emails: type: array description: >- People rows: every email address found, with what checking it showed. items: type: object required: - email - isPersonal properties: email: type: string status: type: string enum: - valid - invalid - catch-all - unknown - do_not_mail - unverified isPersonal: type: boolean description: A personal address rather than a work one. phones: type: array description: 'People rows: every phone number found.' items: type: object required: - phoneNumber properties: phoneNumber: type: string status: type: string enum: - valid - hq - unverified description: '`hq` is the company''s main line.' primaryEmail: type: string description: 'People rows: the address to write to.' primaryPhone: type: string description: 'People rows: the number to call.' icpMatch: type: boolean description: >- People rows: whether the person fits the organization's ideal customer profile. lists: type: array description: 'People rows: the other lists the person is in.' items: type: object properties: id: type: string name: type: string name: type: string description: Company rows. domain: type: string description: Company rows. industry: type: string description: Company rows. employeeCount: type: integer description: 'Company rows: the headcount on LinkedIn.' revenue: type: string description: Company rows. headquartersCountry: type: string description: Company rows. engagement: type: string description: >- How the row's person or company engaged with campaigns. source: type: string description: >- How the row came into the workspace, such as `csv_upload`. location: type: object properties: city: type: string state: type: string country: type: string columnValues: type: object additionalProperties: true description: >- The values of the list's own columns, by column id. `GET /v1/lists/{listId}` names the columns. pagination: type: object required: - pageSize - total properties: pageSize: type: integer nextCursor: type: string description: >- Send as `cursor` for the next page. Absent on the last page. total: type: integer description: Everything that matches, across every page. example: type: people data: - id: 6a1f0c2b9d4e8a7f3c5b2e22 firstName: Ana lastName: Costa linkedinUrl: https://www.linkedin.com/in/ana-costa jobTitle: Head of Operations companyName: Northwind Freight companyDomain: northwind.example emails: - email: ana.costa@example.com status: valid isPersonal: false phones: [] primaryEmail: ana.costa@example.com lists: - id: 6a1f0c2b9d4e8a7f3c5b2e20 name: Portugal freight ops source: csv_upload location: city: lisbon country: portugal columnValues: 6a1f0c2b9d4e8a7f3c5b2e24: Runs a 40-truck fleet pagination: pageSize: 100 nextCursor: MjoxMDA total: 242 '429': $ref: '#/components/responses/RateLimited' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/ServerError' security: - apiKey: [] components: headers: RequestId: description: The request's id. Quote it when you write to support. schema: type: string example: req_6a1f0c2b9d4e8a7f3c5b2e10 ChargedUsd: description: What this call cost, in US dollars as an exact six-decimal string. schema: type: string example: '0.000500' BalanceUsd: description: >- The organization's balance after this call, in US dollars as an exact six-decimal string. schema: type: string example: '9.999500' RateLimitLimit: description: >- The calls allowed in the window of the route's limit with the fewest calls left. schema: type: integer example: 20 RateLimitRemaining: description: The calls left in that window. schema: type: integer example: 19 RateLimitReset: description: Seconds until that window resets. schema: type: integer example: 42 RetryAfter: description: Seconds to wait before calling again. schema: type: integer example: 42 responses: RateLimited: description: >- Too many calls. Wait the seconds in Retry-After, then call again. The body is empty. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-Request-Id: $ref: '#/components/headers/RequestId' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Error: description: The request was refused. The body names the reason in `error.code`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: >- Something failed on our side and nothing was charged. Retry with backoff; quote X-Request-Id if it persists. The body is empty. headers: X-Request-Id: $ref: '#/components/headers/RequestId' schemas: Error: type: object required: - error properties: error: type: object required: - code - message - doc_url properties: code: type: string description: >- Stable and machine-readable: branch on it. It never changes meaning. message: type: string description: >- A human-readable explanation for logs. It may be reworded at any time. param: type: string description: The request field the error is about, when there is one. doc_url: type: string description: The code's entry in the errors reference. request_id: type: string description: >- The request's id, as in the X-Request-Id header. Quote it to support. example: error: code: insufficient_balance message: Your balance cannot cover this call. Add funds and try again. doc_url: https://docs.outbound.dev/errors#insufficient_balance request_id: req_6a1f0c2b9d4e8a7f3c5b2e10 securitySchemes: apiKey: type: http scheme: bearer description: >- An API key from the console, starting `ob_live_`, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.