Data types — Notebook, Source, Artifact, and more

The notebooklm-py library returns typed dataclasses from every API call. All types are importable directly from the notebooklm package. Two special str enums—SourceType and ArtifactType—are returned by .kind properties and support both enum and string comparisons, making them easy to use in conditionals and f-strings without casting.

Notebook

Represents a single NotebookLM notebook returned by client.notebooks.list(), create(), get(), and rename().

from notebooklm import Notebook

notebooks = await client.notebooks.list()
for nb in notebooks:
    print(f"{nb.id}: {nb.title} ({nb.sources_count} sources)")

str

required

Unique notebook identifier. Use this ID with all other API calls.

title

str

required

Notebook title as shown in the NotebookLM UI.

created_at

datetime | None

Timestamp when the notebook was created. May be None for older notebooks.

sources_count

int

Number of sources currently in the notebook. Defaults to 0.

is_owner

bool

True if the authenticated user owns this notebook. False for notebooks shared with the user.

Source

Represents a single source inside a notebook. Returned by client.sources.list(), get(), add_url(), add_text(), and related methods.

sources = await client.sources.list(nb_id)
for src in sources:
    print(f"{src.id}: {src.title} ({src.kind})")

str

required

Unique source identifier within the notebook.

title

str | None

Source title. May be the URL if the source has not finished processing yet.

url

str | None

Original URL for web page and YouTube sources. None for uploaded files and pasted text.

created_at

datetime | None

Timestamp when the source was added.

kind

SourceType (property)

Source type as a SourceType str enum. Supports both enum and string comparisons.

from notebooklm import SourceType

if source.kind == SourceType.PDF:
    print("PDF source")

if source.kind == "web_page":   # string comparison also works
    print("Web page source")

SourceType and ArtifactType are str enums, so source.kind == "pdf" and source.kind == SourceType.PDF are both True. You can also use them in f-strings: f"Type: {source.kind}" prints "Type: pdf".

Artifact

Represents an AI-generated artifact such as an audio overview, video, report, quiz, or flashcard deck. Returned by client.artifacts.list(), get(), and generation methods.

artifacts = await client.artifacts.list(nb_id)
for art in artifacts:
    if art.is_completed:
        print(f"{art.title} ({art.kind})")

str

required

Unique artifact identifier. This is the same value as task_id from GenerationStatus.

title

str

required

Artifact title as assigned by NotebookLM.

status

int

required

Numeric processing status. Use the boolean properties below instead of comparing integers directly.

Value	Meaning
`1`	Processing (being generated)
`2`	Pending (queued)
`3`	Completed
`4`	Failed

created_at

datetime | None

Timestamp when the artifact was created.

url

str | None

Download URL when the artifact is completed. None while generation is in progress.

kind

ArtifactType (property)

Artifact type as an ArtifactType str enum.

from notebooklm import ArtifactType

if artifact.kind == ArtifactType.AUDIO:
    path = await client.artifacts.download_audio(nb_id, "podcast.mp4")

is_completed

bool (property)

True when status == 3 (completed). Use this to gate download calls.

is_quiz

bool (property)

True when the artifact is a quiz. Quizzes and flashcards share the same internal type code; use this property rather than comparing kind.

is_flashcards

bool (property)

True when the artifact is a flashcard deck.

AskResult

Returned by client.chat.ask(). Contains the answer text, conversation context for follow-up questions, and a list of cited source passages.

result = await client.chat.ask(nb_id, "What are the main themes?")
print(result.answer)

for ref in result.references:
    print(f"Citation [{ref.citation_number}]: {ref.source_id}")

answer

str

required

The AI-generated answer. Inline citations appear as [1], [2], etc., corresponding to entries in references.

conversation_id

str

required

UUID identifying the current conversation. Pass this to subsequent ask() calls to continue the conversation.

turn_number

int

required

Turn number within the conversation, starting at 1.

is_follow_up

bool

required

True when this question continued an existing conversation.

references

list[ChatReference]

Source passages cited in the answer. See ChatReference below.

raw_response

str

First 1,000 characters of the raw API response. Useful for debugging unexpected answers.

ChatReference

A single source citation within an AskResult. References link inline citation markers such as [1] back to specific passages in source documents.

source_id

str

required

UUID of the source being cited. Use this with client.sources.get_fulltext() to retrieve source content.

citation_number

int | None

The citation number displayed in the answer text (e.g., 1 for [1]).

cited_text

str | None

The text passage from the source. Often a snippet or section header rather than the full quoted passage.

start_char

int | None

Start position in NotebookLM’s internal chunked index. This does not map directly to positions in the fulltext returned by get_fulltext(). Use SourceFulltext.find_citation_context() instead.

end_char

int | None

End position in NotebookLM’s internal chunked index.

chunk_id

str | None

Internal chunk identifier. Useful for debugging; not intended for application logic.

GenerationStatus

Returned immediately by all artifact generation methods (generate_audio(), generate_video(), etc.) and by poll_status(). Use task_id to poll or wait for completion.

status = await client.artifacts.generate_audio(nb_id)
print(f"Task: {status.task_id}, Status: {status.status}")

final = await client.artifacts.wait_for_completion(nb_id, status.task_id)
if final.is_complete:
    await client.artifacts.download_audio(nb_id, "podcast.mp4")

task_id

str

required

The generation task identifier. This becomes the artifact’s id once generation completes.

status

str

required

Current status string: "pending", "in_progress", "completed", "failed", or "not_found".

is_complete

bool (property)

True when status == "completed".

url

str | None

Download URL when status is "completed".

error

str | None

Error message when status is "failed".

error_code

str | None

Structured error code, e.g. "USER_DISPLAYABLE_ERROR" for rate-limit rejections.

Note

Represents a user-created note in a notebook. Returned by client.notes.list(), create(), and get(). Notes are distinct from artifacts—they are user-written content, not AI-generated.

str

required

Unique note identifier.

title

str

required

Note title.

content

str

required

Note text content.

created_at

datetime | None

Timestamp when the note was created.

NotebookDescription

Returned by client.notebooks.get_description(). Contains an AI-generated summary and a list of suggested follow-up questions.

desc = await client.notebooks.get_description(nb_id)
print(desc.summary)
for topic in desc.suggested_topics:
    print(f"  - {topic.question}")

summary

str

required

AI-generated summary of the notebook’s content.

suggested_topics

list[SuggestedTopic]

List of suggested questions to ask about the notebook.

Show SuggestedTopic fields

question

str

The suggested question text shown to the user.

prompt

str

The underlying prompt used to generate this question.

NotebookMetadata

Returned by client.notebooks.get_metadata(). Composes a Notebook with a simplified source list, useful for exports and automation pipelines.

notebook

Notebook

The full Notebook object. Also accessible via shortcut properties id, title, created_at, and is_owner.

sources

list[SourceSummary]

Simplified source list for metadata export. Each entry exposes kind, title, and url.

ShareStatus

Returned by client.sharing.get_status(), set_public(), add_user(), update_user(), and remove_user().

notebook_id

str

required

The notebook this sharing configuration belongs to.

is_public

bool

required

True when the notebook is accessible to anyone with the share link.

access

ShareAccess

required

ShareAccess.RESTRICTED or ShareAccess.ANYONE_WITH_LINK.

view_level

ShareViewLevel

required

ShareViewLevel.FULL_NOTEBOOK (chat, sources, and notes) or ShareViewLevel.CHAT_ONLY.

shared_users

list[SharedUser]

Users who have been explicitly granted access. See SharedUser below.

Public share URL when is_public is True. None otherwise.

SharedUser

A user who has been explicitly granted access to a notebook. Appears in ShareStatus.shared_users.

str

required

The user’s Google account email address.

permission

SharePermission

required

SharePermission.OWNER, SharePermission.EDITOR, or SharePermission.VIEWER.

display_name

str | None

The user’s display name, if available.

avatar_url

str | None

URL to the user’s profile picture, if available.

SourceFulltext

Returned by client.sources.get_fulltext(). Contains the complete text content that NotebookLM has indexed for a source, along with a helper method for locating citation passages.

fulltext = await client.sources.get_fulltext(nb_id, source_id)
print(f"Content type: {fulltext.kind}")
print(f"Length: {fulltext.char_count} chars")
print(fulltext.content[:500])

source_id

str

required

UUID of the source.

title

str

required

Source title.

content

str

required

The full indexed text content used by NotebookLM when answering questions.

url

str | None

Original URL for web page and YouTube sources.

char_count

int

Character count of content.

kind

SourceType (property)

Source type as a SourceType str enum, identical to Source.kind.

find_citation_context()

Use this method to locate citation passages from ChatReference.cited_text within the full source content. The start_char/end_char fields on ChatReference reference NotebookLM’s internal chunk index and do not map to positions in content—use this method instead.

fulltext = await client.sources.get_fulltext(notebook_id, ref.source_id)
matches = fulltext.find_citation_context(ref.cited_text, context_chars=200)

if matches:
    context, position = matches[0]
    if len(matches) > 1:
        print(f"Warning: {len(matches)} matches found, using first")
    print(context)
else:
    print("Citation not found in fulltext")

cited_text

str

required

Text to search for, typically from ChatReference.cited_text.

context_chars

int

Number of surrounding characters to include in each match. Defaults to 200.

Returns list[tuple[str, int]]—a list of (context, position) tuples where position is the start of the match within content. Returns an empty list when no match is found.

Cache SourceFulltext objects when processing multiple citations from the same source to avoid repeated API calls.

AccountLimits

Returned by client.settings.get_account_limits(). Contains the server-reported quota limits for the authenticated account.

notebook_limit

int | None

Maximum number of notebooks the account can own.

source_limit

int | None

Maximum number of sources per notebook.

AccountTier

Returned by client.settings.get_account_tier(). Contains raw NotebookLM tier metadata.

tier

str | None

Internal tier identifier. Use get_account_limits() for quota decisions—the raw tier name may not match active limits.

plan_name

str | None

Human-readable plan name, if available.

Python Client

Types & Exceptions

CLI Reference

Data types — Notebook, Source, Artifact, and more

Notebook

Source

Artifact

AskResult

ChatReference

GenerationStatus

Note

NotebookDescription

NotebookMetadata

ShareStatus

SharedUser

SourceFulltext

find_citation_context()

AccountLimits

AccountTier

Build docs developers (and LLMs) love

Python Client

Types & Exceptions

CLI Reference

Documentation Index

​Notebook

​Source

​Artifact

​AskResult

​ChatReference

​GenerationStatus

​Note

​NotebookDescription

​NotebookMetadata

​ShareStatus

​SharedUser

​SourceFulltext

​find_citation_context()

​AccountLimits

​AccountTier

Build docs developers (and LLMs) love

Notebook

Source

Artifact

AskResult

ChatReference

GenerationStatus

Note

NotebookDescription

NotebookMetadata

ShareStatus

SharedUser

SourceFulltext

find_citation_context()

AccountLimits

AccountTier