> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.beehiiv.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server.

# List publication field values <Badge intent="info" minimal outlined>OAuth Scope: publication_fields:read</Badge>

GET https://api.beehiiv.com/v2/workspaces/publication_field_values

This feature is currently in beta and the API is subject to change.

Retrieve the values a publication field resolves to. Provide exactly one of `publication_id`, for each field of a single publication, or `publication_field_id`, for a single field across every publication in the workspace. Values are reported as they stand. Fetched fields are not retrieved as part of this request; use `fetched_at` to judge how current a value is. Requires an API key with access to every publication in the workspace.

Reference: https://developers.beehiiv.com/api-reference/publication-fields/values-index

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `publication_id` (string, optional) — Return one result per field for this publication. Cannot be combined with `publication_field_id`.
- `publication_field_id` (string, optional) — Return one result per publication for this field. Cannot be combined with `publication_id`. Archived fields are accepted, since their values still resolve in content.
- `status` (enum, optional) — Filter the fields returned for a publication by whether they have been archived. Only applies alongside `publication_id`, and defaults to `active`.
  - Allowed values: `active`, `archived`, `all`
- `limit` (integer, optional) — A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
- `cursor` (string, optional) — **Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination.
- `page` (integer, optional) — **Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned.

## Response

### 200

OK

- `data` (list of PublicationFieldValue, required) — An array of publication field values.
- `limit` (integer, optional) — The limit placed on the results. If no limit was specified in the request, this defaults to 10.
- `has_more` (boolean, optional) — **Cursor pagination only**: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination.
- `next_cursor` (string, optional) — **Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination.
- `page` (integer, optional) — **Offset pagination only**: The page of results returned. Only present when using the deprecated `page` parameter.
- `total_results` (integer, optional) — The total number of results from all pages.
- `total_pages` (integer, optional) — **Offset pagination only**: The total number of pages. Only present when using the deprecated `page` parameter.

## Errors

### 400 Bad Request Error

Bad Request

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 401 Unauthorized Error

Unauthorized. The API key or OAuth access token is missing, invalid, or expired.

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 403 Forbidden Error

Forbidden

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 404 Not Found Error

Resource Not Found

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 429 Too Many Requests Error

Rate Limit Exceeded

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 500 Internal Server Error

Internal Server Error

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

## Types

### PublicationFieldValue

- `publication_field_id` (string, required) — The prefixed ID of the publication field.
- `publication_field_name` (string, required) — The name of the publication field, which is the key it is referenced by in content.
- `publication_id` (string, required) — The prefixed ID of the publication.
- `publication_name` (string, required) — The name of the publication.
- `status` (enum, required) — How the value resolves.
  - Allowed values: `set`, `using_default`, `no_value`, `fetched_ok`, `fetch_failed_stale`, `fetch_failed`, `never_fetched`
- `value` (string, optional) — The value the publication resolves to, falling back to the field's default value. An empty string when neither is set. Null for `json` fields, which hold a whole response body rather than a single value.
- `fetched_at` (integer, optional) — The time the value was last retrieved successfully, measured in seconds since the Unix epoch. Null for fields that are not fetched, and for fetched fields that have never been retrieved successfully.
- `key_values` (list of PublicationFieldKeyValue, optional) — The `json` field's declared keys and the values from the last successful fetch, in declaration order. Null for fields that are not `json`.

### ErrorDetail

- `message` (string, required)
- `code` (string, required)

### PublicationFieldKeyValue

- `key` (string, required) — A key declared by the publication field.
- `value` (string, optional) — The fetched value rendered as a string. Null when the key was omitted, held an object or array, did not match the declared kind, or was too large to render.

## Examples

### By publication

**Response**

```json
{
  "data": [
    {
      "publication_field_id": "pub_field_00000000-0000-0000-0000-000000000000",
      "publication_field_name": "support_email",
      "publication_id": "pub_00000000-0000-0000-0000-000000000000",
      "publication_name": "Morning Brew",
      "status": "set",
      "value": "help@morningbrew.com",
      "fetched_at": null
    },
    {
      "publication_field_id": "pub_field_11111111-1111-1111-1111-111111111111",
      "publication_field_name": "weather",
      "publication_id": "pub_00000000-0000-0000-0000-000000000000",
      "publication_name": "Morning Brew",
      "status": "fetched_ok",
      "value": null,
      "fetched_at": 1700000000,
      "key_values": [
        {
          "key": "condition",
          "value": "Cloudy"
        },
        {
          "key": "temp",
          "value": "71"
        }
      ]
    }
  ],
  "limit": 10,
  "has_more": false,
  "next_cursor": null
}
```

**SDK Code**

```python By publication
import requests

url = "https://api.beehiiv.com/v2/workspaces/publication_field_values"

querystring = {"publication_id":"pub_00000000-0000-0000-0000-000000000000","limit":"10"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript By publication
const url = 'https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go By publication
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby By publication
require 'uri'
require 'net/http'

url = URI("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java By publication
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php By publication
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp By publication
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift By publication
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_id=pub_00000000-0000-0000-0000-000000000000&limit=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### By field

**Response**

```json
{
  "data": [
    {
      "publication_field_id": "pub_field_00000000-0000-0000-0000-000000000000",
      "publication_field_name": "support_email",
      "publication_id": "pub_00000000-0000-0000-0000-000000000000",
      "publication_name": "Morning Brew",
      "status": "set",
      "value": "help@morningbrew.com",
      "fetched_at": null
    },
    {
      "publication_field_id": "pub_field_00000000-0000-0000-0000-000000000000",
      "publication_field_name": "support_email",
      "publication_id": "pub_22222222-2222-2222-2222-222222222222",
      "publication_name": "Marketing Brew",
      "status": "using_default",
      "value": "support@beehiiv.com",
      "fetched_at": null
    }
  ],
  "limit": 10,
  "has_more": false,
  "next_cursor": null
}
```

**SDK Code**

```python By field
import requests

url = "https://api.beehiiv.com/v2/workspaces/publication_field_values"

querystring = {"publication_field_id":"pub_field_00000000-0000-0000-0000-000000000000","limit":"10"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript By field
const url = 'https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go By field
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby By field
require 'uri'
require 'net/http'

url = URI("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java By field
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php By field
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp By field
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift By field
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/workspaces/publication_field_values?publication_field_id=pub_field_00000000-0000-0000-0000-000000000000&limit=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> Build your audience with beehiiv's API and SDKs. Create new subscribers and posts, get real-time notifications of subscription activity, and more.