Run statistics

Graph.add returns an AddResult. Graph.update returns an UpdateResult whose add_result contains the same summaries. This page lists the fields of AddResult, the failure records that its stages return, and the counts of discarded items. See the Python API for the types.

Add result

Field	Type	Meaning
ingestion	IngestStats	documents, sources, skipped, unchanged, and quarantined counts, and quarantined_items, the failure records of the quarantined sources.
chunking	ChunkingStats	chunks, sections, tables, and figures counts.
extraction	ExtractionStats	The counts in Extraction statistics.
escalation	EscalationReport	How many chunks the LLM extractor read and how many it left to the first extractor. See Escalation report.
resolution	ResolutionStats	exact_match_hits, in_batch_groups, ambiguous_count, failed_llm_requests, cap_truncated_pairs, and llm_unavailable_pairs.
merge	MergeStats	nodes_created, nodes_updated, conflicts_resolved, dropped, and the failure fields.
storage	StorageStats	nodes_written, relationships_written, and the failure fields.
chunks	list of Chunk	Every chunk the call produced. Empty unless you pass return_chunks=True.

Failure records

The extraction, merge, and storage stats each have failures, failures_total, and failures_truncated. A stage keeps the first 200 failure records. failures_total counts every failure, and failures_truncated is true when the list was cut.

Each record in failures is a StageFailure.

Field	Meaning
item_id	The chunk id, mention id, or batch id that the stage failed on.
error_type	The class name of the exception.
error_message	The message of the exception.
trace_id	The OpenTelemetry trace id when a recording span is active for the failure.
span_id	The active recording span's id, when available.

Escalation report

AddResult.escalation counts the chunks of one run. The first extractor reads every chunk. A chunk is eligible when that first result is weak, and the escalation budget caps how many eligible chunks the LLM extractor reads, weakest first.

Field	Meaning
mode	The effective extraction mode. A run with no LLM extractor reports gliner.
total	The chunks the run extracted from.
skipped_short	In llm mode, the chunks under EXTRACTION_MIN_ESCALATION_WORDS words that went to no model. Zero in other modes.
eligible	The chunks whose first result was weak enough to escalate. Zero in llm mode.
escalated	The chunks the LLM extractor was called on.
left_for_gliner	The eligible chunks that kept the first result because the budget ran out.
lowest_score_left	The lowest span score among those chunks, or None.
failed	The escalated chunks that kept the first result because the LLM call raised, its answer did not parse, or it returned no entities when the first result had some. Counted inside escalated.
budget_needed	The smallest batch share that would have escalated every eligible chunk in each batch. For a run with several batches, this is the largest per-batch share needed.
primary_seconds, escalation_seconds	Seconds spent in the first extractor and in the LLM extractor, summed over batches.

Extraction statistics

AddResult.extraction is an ExtractionStats.

Field	Meaning
dropped	DroppedCount entries for items extraction discarded. Each entry has kind, label, reason and count. The list is filled whether or not candidates are written. These are run counts, not counts of candidate records currently stored.
candidates_written	Candidate records written to the graph by this run.
candidates_skipped	Discarded items not written because a reviewer already approved or rejected the same content, or because a relation's ends became one entity.

Merge statistics

AddResult.merge.dropped lists relations that the merge stage could not write. Each entry has the same DroppedCount fields.

Drop reasons

Reason	Kind	Meaning
off_pattern	relation	The relation label is declared, but the schema allows no pattern for its endpoint types.
below_relation_cut	relation	The relation score is below its threshold.
unresolved_endpoint	relation	An endpoint does not match a kept entity span.
entity_band	entity	The entity score is between the band floor and entity threshold. This reason is absent when the GLiNER candidate pass is disabled or the mode is llm.
property	property	The LLM returned a property key that the entity type does not declare.
schema_validation	entity, relation	Schema validation removed an undeclared entity or an invalid relation. These counts do not create candidate proposals.
unmapped_endpoint	relation	A relation endpoint has no merged entity. This reason appears in merge.dropped.
merged_self_loop	relation	Both relation endpoints became one entity. This reason appears in merge.dropped.

Property conflicts are counted in merge.conflicts_resolved, not in merge.dropped.

Candidate storage failures abort document replacement even under ErrorPolicy.SKIP, so previously committed evidence is preserved.

Candidate kinds by mode

Set the mode with ExtractionSettings.mode or EXTRACTION_MODE. The table lists the candidate kinds each mode can write.

Kind	gliner	hybrid	llm
off_pattern	Yes	Yes	Yes
below_relation_cut	Yes	Yes	No
unresolved_endpoint	Yes	Yes	No
entity_band	Yes	Yes	No
property	No	Yes, for custom schemas with properties	Yes, for custom schemas with properties

An off_pattern candidate in llm mode has confidence 0.0, because the model does not return a score. A property candidate uses the holder entity's confidence, or 0.0 when the entity has no score.

Related

• How-to: Turn candidates off.
• How-to: Review candidates and grow your schema.
• Explanation: Candidates.