GET /coverage/url-lists/{urlListId} — get a URL list

GET /coverage/url-lists/{urlListId} returns one coverage URL list by id.

Request

GET https://api.octogen.ai/v1/coverage/url-lists/{urlListId}
Authorization: Bearer <your-platform-api-key>

Path parameters

string

required

The list id (cul_...) returned when the list was created.

Example

curl -sS https://api.octogen.ai/v1/coverage/url-lists/cul_01KZAC9QSY5RWSTZ63FGBS50F2 \
  -H "Authorization: Bearer $OCTOGEN_PLATFORM_API_KEY"

Response

string

required

Stable list identifier.

string

required

The list’s name, unique among your live lists.

"provisioning" | "active" | "delete_pending"

required

Lifecycle state. provisioning lists are being set up (the bigQuery field is still null); active lists are exported daily; delete_pending lists are being torn down and disappear when teardown completes.

integer

required

Current number of member URLs (after normalization and dedup).

object | null

required

BigQuery output details once the list is provisioned: exchangeId and listingId name the Analytics Hub listing, sharedDatasetId the shared dataset, and viewId the products view (products_current_v1). The dataset also carries the per-URL url_coverage_v1 view — see the Coverage URL Lists guide. lastExportedAt and lastRowCount describe the most recent daily export, and readerCount is the number of your registered BigQuery Readers with access.

datetime

required

When the list was created.

datetime

required

When the list last changed (membership, status, or export bookkeeping).

Example response

{
  "urlListId": "cul_01KZAC9QSY5RWSTZ63FGBS50F2",
  "name": "q3-campaign",
  "status": "active",
  "urlCount": 5445,
  "bigQuery": {
    "exchangeId": "catalogs_prod",
    "listingId": "coverage_cul_01KZAC9QSY5RWSTZ63FGBS50F2_v1",
    "sharedDatasetId": "coverage_share_cul_01KZAC9QSY5RWSTZ63FGBS50F2_v1",
    "viewId": "products_current_v1",
    "lastExportedAt": "2026-08-06T06:31:12Z",
    "lastRowCount": 1128,
    "readerCount": 1
  },
  "createdAt": "2026-08-05T20:14:03Z",
  "updatedAt": "2026-08-06T06:31:12Z"
}

Errors

Status	`detail`	Meaning
`404`	`"url_list_not_found"`	No list with that id exists in your organization.
`503`	`"url_lists_unavailable"`	The feature is temporarily unavailable. Retry with backoff.

SDK equivalents

import asyncio
from octogen_ai_sdk import OctogenClient

async def main() -> None:
    async with OctogenClient() as client:
        url_list = await client.get_coverage_url_list("cul_01KZAC9QSY5RWSTZ63FGBS50F2")
        if url_list.big_query is not None:
            print(url_list.big_query.listing_id, url_list.big_query.last_row_count)

asyncio.run(main())

import { OctogenClient } from "@octogen-ai/sdk";

const client = new OctogenClient();
const urlList = await client.getCoverageUrlList("cul_01KZAC9QSY5RWSTZ63FGBS50F2");
console.log(urlList.bigQuery?.listingId, urlList.bigQuery?.lastRowCount);

Catalog API

Voyage API

Coverage API

Data Models

GET /coverage/url-lists/{urlListId} — get a URL list

Request

Path parameters

Example

Response

Example response

Errors

SDK equivalents

​Request

​Path parameters

​Example

​Response

​Example response

​Errors

​SDK equivalents

Request

Path parameters

Example

Response

Example response

Errors

SDK equivalents