{ "entries": [ { "terms": [ "royalties", "royalty payments", "royalty contracts", "royalty", "contract term", "contract condition", "rate", "royalty rate", "commission", "contract party", "contract contributor", "territory exclusion", "store exclusion", "carve-out", "carveout", "carve out", "contract lifecycle", "contract status", "terminate", "renew" ], "targets": [ "abacusContract", "abacusContracts", "abacusContractTerm", "abacusContractTerms", "abacusContractTermConditions", "abacusContractTermsByAccount", "abacusContractParties", "abacusContractExclusion", "abacusContractLifecycle", "abacusContractLifecycleSchedule", "abacusContractLifecycleSchedules" ], "related": [ "AbacusContract", "AbacusContractType", "AbacusContractTerm", "AbacusContractTermCondition", "AbacusContractPartyResult", "AbacusContractExclusion", "AbacusContractLifecycle", "AbacusContractLifecycleSchedule" ], "context": "Royalties in Abacus are represented as contracts between the company and a vendor (account). A contract defines terms, parties, exclusions, and lifecycle rules. Key fields: contractId, contractName, contractType, contractStatus, accountId, contractDate, expirationDate. contractType: DISTRIBUTION | NEIGHBOURING_RIGHTS. contractStatus: ACTIVE | INIT | IN_COLLECTION_PERIOD | TERMINATED | TO_BE_TERMINATED. Contract terms define royalty rates and conditions (territories, stores, transaction types). Contract parties are contributors (artists) or labels linked to a contract. Contract exclusions remove specific territories or stores from scope. Contract lifecycle tracks status transitions with renewal schedules: continuously_active, renew_after_certain_date, renew_periodically. Use abacusContracts to list contracts by accountId and abacusContract for a single contract by contractId. Contract lifecycle transitions (e.g., TO_BE_TERMINATED -> TERMINATED) are automated by the Run Controller during accounting runs - they are not triggered by users. The Run Controller groups contracts for batch processing. When a contract is excluded from accounting (isExcludedFromAccountingRun), it is skipped during runs but retains its current status.", "domain": "royalties", "priority": 2, "relationships": [ "Contract -> Account (N:1, via accountId - one account can have many contracts)", "Contract -> ContractTerms (1:N) -> Conditions (1:N) -> TransactionTypes (N:N)", "Contract -> ContractParties (1:N, contributors/artists and labels linked to the contract)", "Contract -> ContractExclusions (1:N, territory or product carve-outs)", "Contract -> RunController (N:1, groups sibling contracts for batch processing)" ], "businessRules": [ "Sibling contracts (same account_id + contract_type) must be in the same run controller", "Contract term types: artist, catalog, contribution, label, product, track, contributor_schedule, contribution_schedule - each has different rate calculation rules; term_rate + commission = 100", "Earnings transfer types: cross_recoup, reclass, override, transfer, nr_transfer - moves money between contracts with rate_type (flat_rate or percent) and input_source (closing_balance, gross_revenue, net_revenue)", "Lifecycle renewal schedules: continuously_active, renew_after_certain_date, renew_periodically; lifecycle statuses: init -> active -> to_be_terminated -> terminated / in_collection_period -> inactive", "Default country exclusion: Russia (RUS) is excluded from all new contracts by default" ], "gotchas": [ "contractType NEIGHBOURING_RIGHTS has completely separate calculation rules from DISTRIBUTION - do not conflate them", "Contract lifecycle transitions are automated by the Run Controller during accounting runs - users cannot manually trigger them", "A contract with isExcludedFromAccountingRun is skipped during runs but retains its current status" ], "examples": [ { "question": "Show me royalty contracts for account 123", "query": "query ($accountIds: [Int]) { abacusContracts(accountIds: $accountIds, limit: 20) { items { contractId contractName contractType contractStatus } totalCount } }", "variables": { "accountIds": "[123]" } }, { "question": "Get details for contract 456", "query": "query ($contractId: ID) { abacusContract(contractId: $contractId) { contractId contractName contractType contractStatus accountId } }", "variables": { "contractId": "456" } } ] }, { "terms": [ "create contract", "create royalty contract", "new contract", "create contract from pdf", "abacuscreatecontractwithlifecycles" ], "targets": [ "AbacusContractWithLifecyclesInput", "AbacusContractInput", "AbacusContractLifecycleScheduleInput" ], "context": "Contract creation in QA goes through graphql-abacus mutations. Entry point: abacusCreateContractWithLifecycles. Follow-ups for the rest of the contract: abacusCreateContractParty, abacusCreateContractAdvance, abacusCreateContractTerm + abacusCreateContractTermConditions, abacusUpdateContractExclusions, abacusCreateContractMechanicalDeductions, abacusCreateContractReserve. Use graphql_type_info to fetch each input type's exact field shape before composing.", "domain": "royalties", "priority": 2, "gotchas": [ "Mutations only work in QA - refused in dev and prod", "Null result from abacusCreateContractWithLifecycles means the resolver finished but produced no contract; an upstream ows-royalties call failed silently", "Lifecycle schedule fields are camelCased and flat: terminationNoticeDetailInterval/Type, renewalOffsetDetailInterval/Type, collectionPeriodDetailInterval/Type; renewalType / period type values are uppercase enums (DAY, MONTH, YEAR; CONTINUOUSLY_ACTIVE, RENEW_AFTER_CERTAIN_DATE, RENEW_PERIODICALLY)" ], "examples": [ { "question": "Create a royalty contract with auto-renewing 1-year lifecycle and 60-day notice", "query": "mutation ($input: AbacusContractWithLifecyclesInput!) { abacusCreateContractWithLifecycles(input: $input) { contractId contractName contractStatus contractType } }", "variables": { "input": "{ \"contract\": { \"accountId\": \"\", \"contractName\": \"\", \"contractType\": \"distribution\", \"executionDate\": \"\", \"isPrimaryContract\": true, \"isExcludedFromAccountingRun\": false, \"referenceSigningEntityId\": \"\", \"runControllerId\": \"\", \"summaryNote\": \"\" }, \"lifecycle\": { \"lifecycleTermStart\": \"\" }, \"lifecycleSchedules\": [ { \"renewalType\": \"RENEW_PERIODICALLY\", \"renewalOffsetDetailInterval\": 1, \"renewalOffsetDetailType\": \"YEAR\", \"terminationNoticeDetailInterval\": 60, \"terminationNoticeDetailType\": \"DAY\" } ] }" } } ] }, { "terms": [ "distribution", "release distribution", "distribute", "distributed", "delivery", "deliver to store", "dsp delivery", "store delivery", "vector", "direct delivery" ], "targets": ["deliveryStore", "deliveryStoresV2"], "related": ["DeliveryStore"], "context": "Distribution tracks how releases and tracks are delivered to digital service providers (DSPs) and stores such as Spotify, Apple Music, Amazon Music, and YouTube Music. The delivery system is internally called 'vector' (Very Efficient Conduit to Our Retailers), formerly 'direct delivery' or 'dd' - it is responsible for encoding and delivering content to stores. Key fields: deliveryId, productId, storeId, deliveryStatus, deliveredAt. Delivery statuses track whether a release has been sent, accepted, or rejected by a store. Use delivery to get delivery details for a product and deliveryStores to list all stores a product has been delivered to. Delivery is the mechanism by which products reach consumers - every release must be delivered to at least one store before it generates revenue.", "domain": "distribution", "priority": 2, "businessRules": [ "Product release statuses follow a pipeline: label_processing -> transfer_to_content -> in_content (or error_correction / action_required)", "Products in label_processing are fully editable; in transfer_to_content they become read-only", "Products must pass content review (release approval) before transitioning from transfer_to_content to in_content", "DeliveryStoreClassification types: AGGREGATOR, CHARTING, COLLECTIONS, FILM_TV, FINGERPRINTING, MARKETING, MUSIC, MUSIC_VIDEO, NR_OWNER, NR_PERFORMER, PHYSICAL, PHYSICAL_SUPPLY_CHAIN, REPORTING_ONLY, RINGTONE, TESTING", "DeliveryStoreStatus: ACTIVE | INACTIVE | ONBOARDING | SUSPENDED | TERMINATED" ], "gotchas": [ "Product statuses in Workstation use snake_case (label_processing, transfer_to_content, in_content) - not the same as GraphQL enum values", "Carveouts are UPC-scoped (not product-ID-scoped) - same UPC across products shares carveouts", "Products in error_correction can submit corrections per-field at release or track level, but some fields are uncorrectable post-delivery" ], "relationships": [ "Product -> DeliveryStore (N:N, via delivery - each product delivered to multiple stores)", "Product -> Carveout (1:N, territory/store restrictions at vendor, subaccount, and product level - cascading)", "DeliveryStore -> Territory (N:N, store availability varies by territory)" ], "examples": [ { "question": "Which stores has product 5678 been delivered to?", "query": "query ($productId: ID!) { deliveryStores(productId: $productId) { storeId storeName deliveryStatus deliveredAt } }", "variables": { "productId": "5678" } } ] }, { "terms": [ "product", "release", "album", "single", "ep", "fingerprint", "content id", "pricing", "price tier", "pre-order", "timed release", "product correction", "bpm", "key", "mood", "audio analysis", "sample", "sample clearance", "cd delivery", "vinyl", "physical order", "catalogue number", "catalog number", "product code", "p line", "c line", "copyright line", "phonogram line", "instant grat", "previewable" ], "targets": ["product", "allProductsSearch", "track"], "related": [ "Product", "FingerprintRule", "OrchardPricingFamily", "OrchardPricingTier", "EffectivePriceCode", "Carveout", "CompleteStoreCarveout", "CompleteTerritoryCarveout", "StoreTerritoryCarveout", "PreOrderType", "CorrectionDetailInput", "AudioAttribute", "PhysicalDeliveryOrder", "PhysicalDeliveryProductResult" ], "context": "Products are music releases (albums, singles, EPs) containing tracks. A product represents a complete release with metadata, artwork, and one or more tracks. Key fields: productId, title, upc, releaseDate, productType, labelId, artistName, trackCount. Product types include ALBUM, SINGLE, EP, COMPILATION. Product Code (also called Catalogue Number) is a user-generated unique product ID required for accounting. The (P) Line is the phonograph copyright symbol identifying the owner of the sound recording copyright, followed by the year of recording. The (C) Line is the copyright symbol for the product package (compilation, artwork, text), followed by the year of creation. Products have pricing families and tiers that control store pricing. Carve-outs restrict territory/store distribution at multiple levels: vendor carve-outs are in the label contract, release-level territory carve-outs inherit from vendor carve-outs and can be adjusted per-release, and at delivery time all levels are combined to determine eligibility. Instant grats define which tracks can be saved/downloaded prior to the sales start date during a pre-order period. Timed release controls the exact time a product becomes available. Fingerprint rules manage content ID revenue collection. Correction workflows handle post-release metadata changes. Audio attributes (BPM, key, mood) are analysis metadata on tracks. Samples track audio sample clearance. Physical delivery manages CD and vinyl manufacturing. Use products to search the catalog and product for details by productId.", "domain": "product", "priority": 2, "businessRules": [ "ProductConfiguration types: DIGITAL_AUDIO | MOVIE | MUSIC_VIDEO | OTHER | PHYSICAL_AUDIO | TV_SHOW", "PricingFamily types: FILM | MUSIC_ALBUM | MUSIC_TRACK | PHYSICAL_MUSIC | VIDEO - pricing tiers are per-family", "ProductArtistRole types: PRIMARY_ARTIST, FEATURED_ARTIST, FEATURE_TO_PRIMARY, COMPOSER, CONDUCTOR, ENSEMBLE, ORCHESTRA, PRODUCER, REMIXER, SINGER, SOLOIST, ARRANGER, CAST, CHORUS, ENGINEER, LYRICIST", "Post-submission validation: 21 error codes (ACCOUNT_BLOCKLIST, ARTWORK, COMPOSER_REQUIRED, etc.) and 5 warning codes (AI_GENERATED_AUDIO, BLOCKLIST, etc.) - errors block delivery, warnings are advisory" ], "gotchas": [ "vendor_id in product response equals account_id - the system uses these interchangeably", "display_upc may differ from canonical manufacturer_upc", "Physical products have boxLot, initialStock, packagingId, wholesalePrice fields not present on digital", "Japan-specific fields: japanDistribution, edition (normal/first_run_limited/limited/period_limited), phonetic translations (katakana)", "Classical genre triggers conditional fields: Orchestra, Conductor, Ensemble, Composer at both product and track level" ], "relationships": [ "Product -> Project (N:1, grouped under project with projectCode)", "Product -> Subaccount (N:1, organizational grouping within vendor)", "Product -> DistributionFormat (1:1, digital/physical/music_video with mediaId for physical)", "Product -> Tracks (1:N, via track listing)", "Track -> ISRC (1:1, auto-generated or manually assigned)" ], "examples": [ { "question": "Get details for product with UPC 123456789012", "query": "query ($upc: String!) { allProductsSearch(term: $upc, limit: 1) { items { productId title upc releaseDate productType artistName trackCount } totalCount } }", "variables": { "upc": "123456789012" } } ] }, { "terms": [ "product metadata", "content type", "digital audio", "ownership sound recording", "performance sound recording", "fingerprint sound recording", "product section", "product fields", "product header", "reference metadata", "display featuring as primary" ], "targets": ["product", "allProductsSearch", "track"], "related": ["Product", "Track"], "context": "Product metadata is organized into content types and UI sections. The four content types are: (1) Digital Audio - the standard release product with tracks, pricing, and delivery metadata; (2) Ownership Sound Recording - tracks ownership and rights claims with collections start/end dates, territory rights, and ISRC associations; (3) Performance Sound Recording - tracks performer contributions, recording details, country of recording/mastering, and NR (neighbouring rights) data like contributor roles and NR Priority (High/Medium/Low); (4) Fingerprint Sound Recording - tracks audio fingerprint delivery to services, with rights attributes, approved services, and content matching data. Product fields are organized into UI sections: Product Header (IDs, status, artist), Basics (name, format, genre, version, label info), Tracks (track names, audio, ISRC, explicit content, lyrics), Contributors (primary/featuring/session artists, classical roles like orchestra/conductor/ensemble/composer), Scheduling & Pricing (release date, pre-order, instant grats, pricing intervals), Reference Metadata (genre, duration, year of recording/release, country info), Instances (product appearances across catalogs, sales dates), Rights (territory ownership, collection dates, rights percentages), Delivery (delivery files, dates, services). Classical music triggers conditional fields: when Genre = Classical, Orchestra, Conductor, Ensemble, and Composer fields become available at both product and track level. Display Featuring As Primary is a store-specific rule where at Spotify, Tidal, and Deezer, featured artists can be delivered as primary artists while remaining featured at all other services.", "domain": "product-metadata", "priority": 1 }, { "terms": [ "user", "login", "identity", "password", "reset password", "notification", "notification settings", "alerts" ], "targets": ["identityByEmail", "identityById"], "related": [ "Identity", "Profile", "Notification", "NotificationSettings", "IdentityNotifications" ], "context": "Users are platform identities with profiles, permissions, and authentication via Auth0. Key fields: identityId, email, firstName, lastName, auth0Id, status, createdAt. Each identity has a profile with role, permissions, and associated accounts. Authentication is handled via Auth0 SSO. Notifications deliver platform alerts to users with configurable settings for different notification types (email, in-app) and delivery channels. Use identityByEmail to look up a user by email address and identityById for lookup by internal ID.", "domain": "user", "priority": 2, "examples": [ { "question": "Look up user by email address", "query": "query ($email: String!) { identityByEmail(email: $email) { identityId email firstName lastName status } }", "variables": { "email": "jane.doe@example.com" } } ] }, { "terms": [ "analytics", "stats", "metrics", "reporting", "feed status", "data availability", "dsp data freshness" ], "targets": ["analyticsDataAvailability", "analyticsFeeds"], "related": ["AnalyticsDataAvailability", "AnalyticsFeed"], "context": "Analytics provides streaming data availability info, feeds, and performance reporting across DSPs. Key fields: feedId, storeName, dataAvailableThrough, lastUpdated, status. Data availability shows when the latest data was received from each store/DSP. Analytics feeds track ingest status of streaming data pipelines. Use analyticsDataAvailability to check if data from a specific store is current, and analyticsFeeds to monitor feed health. Common query pattern: check data availability before running revenue reports to ensure completeness.", "domain": "analytics", "priority": 2, "examples": [ { "question": "Check data availability for all stores", "query": "query { analyticsDataAvailability { storeName dataAvailableThrough lastUpdated status } }", "variables": {} } ] }, { "terms": [ "publishing", "songwriter", "composition", "mechanical", "pub admin", "publishing admin", "publishing administration" ], "targets": [ "publishingComposition", "publishingCompositions", "publishingAgreements" ], "related": ["PublishingComposition", "PublishingAgreement"], "context": "Publishing covers songwriter compositions, mechanical rights, publishing agreements, and publishing royalties. Key fields: pubSongId, title, iswc, writers, publishers, shares. A composition is the underlying musical work (lyrics + melody), distinct from the sound recording. Publishing agreements define the relationship between songwriters and publishers with territory, share, and term details. Mechanical rights are the right to reproduce a composition. Use publishingCompositions to search for compositions and publishingAgreements to view publishing deals.", "domain": "publishing", "priority": 2, "examples": [ { "question": "Search for compositions by title", "query": "query ($title: String!) { publishingCompositions(filter: { title: $title }, limit: 10) { compositions { id pubSongId title iswc } totalCount } }", "variables": { "title": "Shape of You" } } ] }, { "terms": [ "neighboring rights", "neighbouring rights", "performance rights", "nr priority", "nr id", "sound recording type", "collection society", "collections start date", "collections end date", "rights period" ], "targets": ["nrContributions", "nrContributors"], "related": ["NrContribution", "NrContributor"], "context": "Neighbouring rights cover performer and producer rights for public performance and broadcast of sound recordings. These are distinct from publishing/mechanical rights - they compensate performers and producers when recordings are played on radio, TV, or in public venues. Key fields: nrId, isrc, performerName, producerName, territory, collectionSociety. NR data is tracked through two sound recording types: Performance Sound Recordings (contributor details, roles, country of contribution, number of primary performers, NR Priority) and Fingerprint Sound Recordings (audio fingerprint delivery to services like Meta, rights attributes, territory claims). NR Priority is an internal KNR metric (High/Medium/Low) defining the business importance of a contribution. Collections Start Date marks when rights ownership began; Collections End Date marks when they expire. Each contribution tracks the contributor's country of citizenship and their role (instrument, production, arrangement). Neighbouring rights contracts in Abacus use contractType: NEIGHBOURING_RIGHTS. Collection is managed through societies (PPL, GVL, SENA, etc.) via delivery orders.", "domain": "neighbouring-rights", "priority": 2 }, { "terms": [ "account", "vendor account", "payee account", "abacus account", "d3", "distributor label", "parent account", "child account", "awal", "awal-uk", "awal-core", "awal-us", "gda", "gated diy artist", "knr", "kollective neighbouring rights", "orchard account", "label account", "account hierarchy" ], "targets": ["abacusAccount", "abacusAccounts"], "related": ["AbacusAccount"], "context": "Accounts represent vendor/payee entities in the Abacus royalties system. Account = vendor in Abacus; account_id = vendor_id. Key fields: accountId, accountName, accountStatus, paymentEntity, signingEntity, currencyCode, payeeId, taxInfoId. Each account has associated payee info (bank details/Payoneer), tax info (residence, WHT rates, exemptions), payment terms (frequency, currency, entity), payment holds, and payment minimums. Accounts are the central entity linking contracts, revenue, payments, and ledger entries. Use abacusAccounts to search by name/term and abacusAccount for details by accountId. The owner field distinguishes Sony business units: Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR (Kollective Neighbouring Rights), etc. Each has its own operational processes. Filter by owner to scope queries to a specific business unit. A D3 (distributor label) account is a parent account that has child sub-label accounts under it. GDA (Gated DIY Artist) accounts allow artists to become a contracted vendor directly. Labels often have parent/child account structures with multiple sub-accounts (e.g., Rimas has 11 sub-accounts: Rimas Entertainment, Rimas Sonar, Rimas Mexico, Rimas Classics, etc.). When querying revenue for a label group, search for all related sub-accounts, not just the primary account.", "domain": "account", "priority": 2, "relationships": [ "Account -> Contracts (1:N, via accountId)", "Account -> Payee (1:1, payment method - Payoneer)", "Account -> TaxInfo (1:1, W-9/W-8 forms, WHT rates, VAT status)", "Account -> PaymentTerms (1:1, schedule and currency)", "Account -> PaymentHold (0..1, blocks all disbursements when active)", "Account -> Subaccounts (1:N, for D3 parent labels)", "Account -> LedgerEntries (1:N, financial transaction history)" ], "businessRules": [ "Account types (owner field): Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR (Kollective Neighbouring Rights), GDA (Gated DIY Artist)", "VendorStatus lifecycle: PITCHED -> VERBAL -> SIGNED -> APPROVED -> INACTIVE -> DELETION (also: PENDING, WAITING_FOR_APPROVAL, PASSED)", "VendorType taxonomy: CATALOG | CLIENT_SERVICES | D3 | FILM | FRONTLINE | TEST | TV", "Payment eligibility requires: complete payee info + complete tax info + no active holds + balance > minimum threshold", "Payment services: PAYONEER | SAP | CONVERA | PAYONEER_WHITELABEL | PAYONEER_WIRE | PREEXISTING_PAYONEER_ACCOUNT | PAYCHEX", "D3 parent labels have child sub-label accounts; query all sub-accounts for full label revenue" ], "gotchas": [ "account_id = vendor_id - the system uses these interchangeably", "When querying revenue for a label group, search all sub-accounts under the D3 parent, not just the primary account", "Brand Experience (The Orchard, AWAL, KNR, SME) determines the UI users see - not directly a data filter" ], "examples": [ { "question": "Search for vendor accounts matching 'Sony'", "query": "query ($searchTerm: String) { abacusAccounts(searchTerm: $searchTerm, limit: 20) { items { accountId accountName } totalCount } }", "variables": { "searchTerm": "Sony" } }, { "question": "Get account details for account 789", "query": "query ($accountId: ID!) { abacusAccount(accountId: $accountId) { accountId accountName accountStatus currencyCode } }", "variables": { "accountId": "789" } } ] }, { "terms": [ "vendor hierarchy", "label hierarchy", "sublabel", "sub-account", "vanity label", "account structure", "parent label", "child label", "parent company", "company", "brand experience", "altafonte", "above board", "foundation media", "drm", "label participant" ], "targets": ["abacusAccount", "abacusAccounts"], "related": ["AbacusAccount"], "context": "The full platform hierarchy from top to bottom is: Parent Company -> Company -> Account -> Subaccount. Parent Companies are the highest business rollup (values: SME, The Orchard). Company represents the business within SME that owns the relationship - values include The Orchard, Altafonte, AWAL, KNR, DRM, Above Board, Mass Appeal, Foundation Media. Account (historically called 'Vendor' or 'Label') is the specific legal entity that signed a distribution agreement. A D3 (distributor label) account is a parent with child sub-label accounts under it. Subaccounts belong to D3-type accounts in the permissions hierarchy. An imprint (also called a vanity label) is a branded label name within an account structure - the record label name as it appears on the product. Brand Experience determines what UI users see (4 types: The Orchard, AWAL, KNR, SME). Artists have two identities: Label Participant (account-scoped, privately owned by one account) and Global Participant (cross-account, identified by Spotify Artist ID, aggregating the artist's public-facing presence across the industry). Revenue rolls up through the hierarchy. When querying for a label group, search all subaccounts under the D3 parent.", "domain": "platform-hierarchy", "priority": 2, "examples": [ { "question": "List all accounts (to find subaccount structure)", "query": "query ($searchTerm: String) { abacusAccounts(searchTerm: $searchTerm, limit: 50) { items { accountId accountName accountStatus } totalCount } }", "variables": { "searchTerm": "Rimas" } } ] }, { "terms": [ "statement", "statement period", "accounting period", "accounting cycle" ], "targets": [ "abacusStatementPeriods", "abacusStatementPeriod", "abacusStatementPeriodsList", "abacusCurrentStatementPeriod", "abacusAccountingPeriods", "abacusAccountingPeriod" ], "related": [ "AbacusStatementPeriod", "AbacusAccountingPeriod", "AbacusAccountingRun" ], "context": "Statement periods are time-based groupings for royalty calculations - typically monthly cycles. Key fields: statementPeriodId, name, startDate, endDate, status, accountingPeriods. statement_period_status: OPEN | CURRENT | CLOSED. Each statement period contains one or more accounting periods, which execute accounting runs to compute revenue and balances. Sequential monthly cycles ensure consistent royalty processing. Use abacusCurrentStatementPeriod to get the active period and abacusStatementPeriods for recent/upcoming periods.", "domain": "accounting", "priority": 2, "relationships": [ "StatementPeriod -> AccountingPeriod (1:N, one per contract_type: distribution, neighbouring_rights)", "AccountingPeriod -> AccountingRun (1:N, each run produces results for contracts in scope)", "AccountingRun -> RunController (N:1, groups sibling contracts for batch processing)" ], "businessRules": [ "Statement periods are identified by sequential integer IDs (e.g., P316) that increment by 1 each month", "Statement period close preconditions (all 5 required): (1) status must be CURRENT, (2) all accounting periods CLOSED, (3) all balances closed, (4) all payment entities visible to customer, (5) next sequential period must exist", "Accounting run full status machine: NO_ACTION_TAKEN -> WAITING_TO_RUN -> RUNNING -> COMPLETE -> COMMITTING -> COMMITTED (or ERROR at any step; INVALID auto-creates a clone run)" ], "gotchas": [ "Statement periods are global (not per-account); per-account revenue totals use a different query (moneyhub)", "Accounting periods are scoped by contract_type; a statement period has separate accounting periods for distribution vs. neighbouring rights" ], "examples": [ { "question": "List all statement periods", "query": "query { abacusStatementPeriods { recent { statementPeriodId name startDate endDate } upcoming { statementPeriodId name startDate endDate } } }", "variables": {} }, { "question": "What is the current statement period?", "query": "query { abacusCurrentStatementPeriod { statementPeriodId name startDate endDate } }", "variables": {} } ] }, { "terms": [ "payment", "payment group", "pay vendor", "payment batch", "send payment", "payment hold", "hold payment", "block payment", "on hold", "payout", "when do we get paid", "when will we get paid", "payment eligibility", "eligible for payment", "payment ready" ], "targets": [ "abacusPaymentGroup", "abacusPaymentGroups", "abacusPaymentGroupPayment", "abacusPaymentGroupPayments", "abacusPaymentGroupPaymentAccounts", "abacusPaymentGroupPaymentOverview", "abacusPaymentGroupPaymentAccount", "abacusPendingPaymentByAccount", "abacusPaymentHold", "abacusPaymentHoldHistory", "abacusPaymentMinimum", "abacusPaymentMinimums", "abacusAccountPaymentTerm" ], "related": [ "AbacusPaymentGroup", "AbacusPaymentGroupPayment", "AbacusPaymentGroupPaymentAccount", "AbacusPaymentHold", "AbacusPaymentHoldHistory", "AbacusPaymentMinimums", "AbacusAccountPaymentTerm" ], "context": "Payment groups organize vendor payments into batches for processing. Key fields: paymentGroupId, groupName, isReusable. Payment group statuses flow: INIT -> RUNNING -> COMPLETE -> APPROVED -> REJECTED. PaymentGroupPayment is the actual batch; PaymentGroupPaymentAccount links individual accounts to a batch. Eligibility requires: complete payment info, complete tax info, no payment holds, balance > minimum. Payment holds suspend payments for an account with a reason and start date. Payment minimums set the threshold balance required before issuing payment. Payment terms define schedule (30/45/60/90 days after month/quarter/half-year end), currency, and payment entity. Use abacusPaymentGroups to list batches and abacusPaymentHold to check hold status.", "domain": "payments", "priority": 2, "relationships": [ "PaymentGroup -> PaymentGroupPayment (1:N, individual payment batches)", "PaymentGroupPayment -> PaymentGroupPaymentAccount (1:N, links accounts to a batch)", "Account -> PaymentHold (0..1, active hold blocks all disbursements)", "Account -> PaymentMinimum (1:1, threshold required before payment)" ], "businessRules": [ "Payment group status flow: INIT -> RUNNING -> COMPLETE -> APPROVED -> REJECTED; action flow: generate_payments -> generate_export -> upload_approval -> send_payments", "Payment schedules: 30/45/60/90 days after month-end, quarter-end, or half-year-end (13 values including TEMPORARY)", "PaymentGroupPayment statuses: INIT -> ATTACHED_TO_PAYMENT -> PAID (or RETURNED)", "Supported payment currencies: USD, AUD, CAD, CHF, DKK, EUR, GBP, JPY, NOK, NZD, SEK" ], "gotchas": [ "Payment eligibility requires ALL 8 conditions: (1) balance >= account minimum, (2) balance >= currency minimum, (3) payment_eligibility = approved, (4) tax_eligibility = complete, (5) no blocking prior payment, (6) no active hold, (7) Payoneer program + payee set, (8) group criteria match", "Only one payee per account; different payees for different contracts requires separate accounts", "PaymentEntity determines payment method (Payoneer, bank transfer) based on country + currency combination", "Payment hold scheduling is non-obvious: is_on_hold=false + start_date=future means 'currently on hold UNTIL that date'" ], "examples": [ { "question": "List payment groups", "query": "query { abacusPaymentGroups(limit: 20, offset: 0) { items { paymentGroupId groupName isReusable } totalCount } }", "variables": {} }, { "question": "Check payment holds for account 123", "query": "query ($accountId: ID!) { abacusPaymentHold(accountId: $accountId) { holdReason startDate endDate isActive } }", "variables": { "accountId": "123" } } ] }, { "terms": [ "advance", "advance payment", "contract advance", "recoupment", "recoup", "pending advance", "paid advance", "cross-collateralization", "cross-collateralisation", "cross collateralize" ], "targets": [ "abacusContractAdvance", "abacusContractAdvancesPending", "abacusContractAdvancesPaid" ], "related": ["AbacusContractAdvance"], "context": "Contract advances are upfront payments to vendors, tracked through a milestone-based lifecycle. Key fields: contractAdvanceId, contractId, amount, currencyCode, vatAmount, withholdingTaxAmount, amountAfterWithholdingAndVat, advanceStatus, milestone, milestoneDate, advanceDescription. Advance statuses: NOT_QUALIFIED -> QUALIFIED -> APPROVED -> PENDING_PAYMENT -> PAID (can be DELETED at any stage). Milestones: contract_execution, delivery, fund_contingent, fund_non_contingent, option, recoupment, sales_milestone, scheduled_installment, other. Advances recoup against future royalty earnings - revenue earned offsets the advance balance until fully recouped. Cross-collateralization is when revenue earned on one contract can be used to pay off (recoup) an advance on another contract under the same account. Use abacusContractAdvancesPending for unpaid advances and abacusContractAdvancesPaid for completed advances. Filter by contractId.", "domain": "advances", "priority": 2, "businessRules": [ "Advances must be fully recouped before royalties become payable on a contract", "Cross-collateralization allows revenue from one contract to recoup advances on another under the same account", "Withholding tax and VAT on advances are calculated per country of tax residence and treaty status" ], "gotchas": [ "Advance status flow: NOT_QUALIFIED -> QUALIFIED -> IN_REVIEW -> PENDING_PAYMENT -> APPROVED -> PAID (DELETED is soft-delete at any stage; cannot delete PAID)", "Status transitions enforce ordering: in_review requires prior qualified; pending_payment requires prior in_review", "Statuses qualified through paid require vat_amount and withholding_tax_amount fields; milestone_date cannot be in the future", "Exchange rates are locked at advance creation time, not at payment time", "Milestones: contract_execution, delivery, fund_contingent, fund_non_contingent, recoupment, scheduled_installment, sales_milestone, option, other" ], "examples": [ { "question": "Show pending advances for contract 456", "query": "query ($contractId: ID!) { abacusContractAdvancesPending(contractId: $contractId, limit: 20) { items { contractAdvanceId amount currencyCode status milestone } totalCount } }", "variables": { "contractId": "456" } } ] }, { "terms": [ "reserve", "contract reserve", "reserve rate", "reserve release", "reserve schedule" ], "targets": ["abacusContract", "moneyhubReserveReleaseSchedules"], "related": ["AbacusContractReserve", "MoneyhubReserveReleaseSchedule"], "context": "Reserves are percentages of royalties held back to cover returns, disputes, and adjustments, released on a schedule over months. Key fields: reserveId, contractId, reserve_rate (Numeric 5,2), reserve_release_offset_in_months, installments_in_months, startDate, endDate. Reserve rates are set per contract and define how much of each royalty payment is withheld. Release schedules determine when reserved amounts are paid out - typically in installments over several months after the initial hold period. Use moneyhubReserveReleaseSchedules to view future release dates and amounts for an account.", "domain": "reserves", "priority": 2, "examples": [ { "question": "View reserve release schedule for account 123", "query": "query ($accountId: ID!) { moneyhubReserveReleaseSchedules(accountId: $accountId) { statementPeriodName releaseAmount currencyCode contractId } }", "variables": { "accountId": "123" } } ] }, { "terms": [ "flowthrough", "flow through", "flowthrough payment", "pass through", "paythrough", "pay through", "pay through contract", "pay through contracts", "paythrough contract", "paythrough contracts" ], "targets": ["abacusContractFlowthrough", "abacusContract"], "related": [ "AbacusContractFlowthrough", "AbacusWorksheetFlowthroughBatch" ], "context": "Flowthroughs direct a percentage of royalties from one contract to a third party (another account/contract). Key fields: contractFlowthroughId, flowthroughRate, flowthroughStatus, recoupmentCap, hasAutomaticShutoff, referenceFlowthroughCalculation. Flowthrough statuses: ACTIVE | SHUTOFF | PAUSED. There are 4 calculation formulas determined by referenceFlowthroughCalculation. Flowthroughs can have recoupment caps (max amount to flow through) and automatic shutoff when the cap is reached. Flowthrough batches handle bulk processing of flowthrough payments. Use abacusContractFlowthrough to view flowthroughs for a contract. Revenue for paythrough contracts flows through adjustments (LEDGER_ADJUSTMENT_DETAIL and LEDGER_ADJUSTMENT_APPLIED tables), NOT the standard balances pipeline. If standard revenue queries return empty results for an account, check whether the contract is a paythrough - the revenue will appear in adjustment/flowthrough views instead.", "domain": "flowthrough", "priority": 2, "businessRules": [ "Flowthrough status (ACTIVE | PAUSED | SHUTOFF) is independent of the parent contract status", "Flowthroughs can have recoupment caps; auto-shutoff triggers when the cap is reached", "4 calculation formulas exist (determined by reference_flowthrough_calculation_id)" ], "gotchas": [ "Revenue for paythrough contracts flows through adjustments (LEDGER_ADJUSTMENT tables), NOT the standard balances pipeline", "If standard revenue queries return empty for an account, check whether the contract is a paythrough - revenue appears in adjustment/flowthrough views", "PAUSED temporarily stops distribution; SHUTOFF permanently disables it" ], "examples": [ { "question": "List flowthroughs for contract 456", "query": "query ($contractId: ID!) { abacusContractFlowthrough(contractId: $contractId) { contractFlowthroughId flowthroughRate flowthroughStatus hasAutomaticShutoff recoupmentCap } }", "variables": { "contractId": "456" } } ] }, { "terms": [ "adjustment", "worksheet adjustment", "correction", "royalty adjustment" ], "targets": [ "abacusWorksheetAdjustments", "abacusWorksheetAdjustmentDetails", "abacusWorksheetAdjustmentsAndDetails", "abacusWorksheetAdjustmentsAccounts", "abacusWorksheetAdjustmentsContracts" ], "related": ["AbacusWorksheetAdjustment", "AbacusLedgerAdjustment"], "context": "Adjustments are corrections or modifications to royalty calculations, imported via files or created manually. Types include royalty_reversal and royalty_correction. Key fields: adjustmentId, accountId, contractId, amount, currencyCode, adjustmentType, status, description. Adjustments can be one-off corrections or batch adjustments uploaded via adjustment files. The lifecycle is: uploaded (not_approved) -> approved -> applied to ledger. The AI agent can generate adjustment files to eliminate manual Excel work. Use abacusWorksheetAdjustments to list adjustments and abacusWorksheetAdjustmentsAccounts/Contracts to filter by account or contract. Cross-account transfers require separate adjustment rows per account - a debit row on the source account and a credit row on the destination account, potentially in different currencies (e.g., GBP debit on account A, USD credit on account B). Each row must reference the correct contract and statement period.", "domain": "adjustments", "priority": 2, "businessRules": [ "Adjustment lifecycle: uploaded (not_approved) -> approved -> applied to ledger", "Cross-account transfers require separate rows: a debit on source account and credit on destination, potentially in different currencies", "95 valid adjustment types exist; 'Account Expense' is rejected by the import pipeline" ], "gotchas": [ "All adjustment field values must be strings, including numeric fields like account_id and amount", "If adjustment_type is 'Flowthrough', the apply_to_flowthrough_payment flag (Y/N) is required", "If distribution_type is set on an adjustment row, UPC is required" ], "examples": [ { "question": "List adjustment accounts for statement period adjustment file 789", "query": "query ($statementPeriodAdjustmentFileId: ID!) { abacusWorksheetAdjustmentsAccounts(statementPeriodAdjustmentFileId: $statementPeriodAdjustmentFileId, limit: 20) { items { accountId accountName contractCount totalAdjustmentAmount } totalCount } }", "variables": { "statementPeriodAdjustmentFileId": "789" } } ] }, { "terms": [ "ledger", "closing balance", "opening balance", "ledger entry", "debit", "credit" ], "targets": [ "abacusLedgerAccountContractList", "abacusLedgerAdjustments", "abacusLedgerAccountingRunBalance", "abacusAccount" ], "related": [ "AbacusAccountLedger", "AbacusLedgerAccountContract", "AbacusLedgerAccountingRunBalance" ], "context": "The ledger tracks all financial entries (credits/debits) per account and contract. Key fields: ledgerId, accountId, contractId, eventName, amount, currencyCode, statementPeriodId, createdAt. INSERT-only - entries are never updated or deleted. Positive amounts = credit (Orchard owes account), negative amounts = debit (deductions from account). Entries include revenue, reserves taken, reserves released, advances applied, adjustments, and payments. Run balances show per-contract revenue breakdown per accounting run. Use abacusLedgerAccountContractList for ledger entries by account and abacusLedgerAccountingRunBalance for per-run breakdowns.", "domain": "ledger", "priority": 2, "relationships": [ "LedgerEntry -> Account (N:1, via accountId)", "LedgerEntry -> Contract (N:1, via contractId)", "LedgerEntry -> StatementPeriod (N:1, via statementPeriodId)", "LedgerAccountingRunBalance -> AccountingRun (N:1, per-run revenue breakdown)" ], "businessRules": [ "Ledger is INSERT-only - entries are never updated or deleted", "Positive amounts = credit (Orchard owes account), negative = debit (deductions)", "Balance = earned revenue + advances applied + adjustments - reserves taken - payments made" ], "gotchas": [ "Two period references exist on ledger adjustments: apply_to_statement_period_id (when applied) and activity_statement_period_id (when incurred)", "Moneyhub ledger adjustments return amounts in payee currency; standard ledger adjustments use the original currency" ], "examples": [ { "question": "Show ledger entries for account 123", "query": "query ($accountId: ID!) { abacusLedgerAccountContractList(accountId: $accountId, limit: 50) { items { contractId eventName amount currencyCode statementPeriodId } totalCount } }", "variables": { "accountId": "123" } } ] }, { "terms": ["sales file", "sales data", "sales upload"], "targets": ["abacusSalesFile"], "related": ["AbacusSalesFile"], "context": "Sales files are uploaded data files containing streaming/sales data for an accounting period. Key fields: salesFileId, accountingPeriodId, fileName, rowCount, usdAmount, uploadDate, status. Each file represents a batch of consumption data from a store/DSP that feeds into accounting runs for royalty calculation. Row counts and USD amounts provide a quick summary of file contents. Use abacusSalesFile to check upload status and content summaries for a given accounting period.", "domain": "sales", "priority": 1 }, { "terms": ["payee", "account payee", "bank details", "payoneer"], "targets": ["abacusAccountPayee", "abacusAccountPayeeHistory"], "related": [ "AbacusAccountPayee", "AbacusAccountPayeeHistory", "PayeeCollaborator" ], "context": "Payees are payment recipients linked to accounts. Key fields: payeeId, accountId, paymentMethod, payoneerAccountId, bankName, bankAccountNumber, routingNumber, status, isEligible. Payment methods include Payoneer, SAP (wire transfer), and direct deposit. Payee eligibility is required for payment processing - an account cannot receive payments without complete payee info. Payoneer integration connects to Payoneer's payment network. Change history tracks all modifications to payee details for audit purposes. Use abacusAccountPayee to get current payee info and abacusAccountPayeeHistory for change log.", "domain": "payee", "priority": 2, "examples": [ { "question": "Get payee details for account 789", "query": "query ($accountId: ID!) { abacusAccountPayee(accountId: $accountId) { payeeId paymentMethod status isEligible bankName } }", "variables": { "accountId": "789" } } ] }, { "terms": [ "tax info", "tax residence", "withholding tax", "wht", "tax exemption", "1099", "1042-s", "1042s", "w-9", "w9", "w-8", "w8", "w-8ben" ], "targets": ["abacusAccountTaxInfo", "abacusAccountTaxInfoHistory"], "related": ["AbacusAccountTaxInfo", "AbacusAccountTaxInfoHistory"], "context": "Account tax info includes country of tax residence, VAT exemption status, withholding tax applicability, and tax treaty claims. Key fields: accountTaxInfoId, accountId, countryOfTaxResidence, isVatExempt, isWhtApplicable, isTaxTreatyClaimed, taxEmploymentType. Tax info completeness is required for payment eligibility. History tracks all changes for audit trail. Withholding tax rates are determined by the combination of tax residence country and applicable treaties. Use abacusAccountTaxInfo for current tax details and abacusAccountTaxInfoHistory for change log.", "domain": "tax", "priority": 1 }, { "terms": [ "revenue", "revenue report", "revenue by country", "revenue by artist", "revenue by store", "revenue by product", "revenue by track", "revenue by imprint", "revenue by subaccount", "revenue by month", "ppl", "prs", "gema", "ascap", "collecting society", "cmo" ], "targets": [ "moneyhubAllTimeAccountRevenue", "moneyhubCustomReports", "moneyhubRevenueByCountry", "moneyhubRevenueByProduct", "moneyhubRevenueByRecording", "moneyhubRevenueByStore", "moneyhubRevenueByTransactionType", "moneyhubRevenueByArtist", "moneyhubRevenueByImprint", "moneyhubRevenueBySubaccount", "moneyhubRevenueByTrack", "moneyhubRevenueByActivityMonth", "moneyhubRevenueByStatementPeriod", "moneyhubRevenueByAccountStatementPeriod" ], "related": [ "MoneyhubAccountRevenue", "MoneyhubCustomReport", "MoneyhubRevenueByArtistList", "MoneyhubRevenueByImprintList", "MoneyhubRevenueBySubaccountList", "MoneyhubRevenueByTrackList", "MoneyhubRevenueByActivityMonthList", "MoneyhubRevenueByStatementPeriod" ], "context": "Moneyhub provides revenue breakdowns by artist, country, store, imprint, product, recording, track, subaccount, transaction type, activity month, and statement period. Key fields: accountId, netRevenuePayeeCurrency, grossRevenuePayeeCurrency, statementPeriodIdStart, statementPeriodIdEnd, limit, orderBy, orderDir. Revenue can be broken down by source/store/DSP, including collecting societies like PPL, PRS, GEMA, ASCAP. Custom reports allow flexible multi-dimension breakdowns. All revenue queries are scoped by accountId and optionally filtered by statement period range. Use moneyhubAllTimeAccountRevenue for summary totals and moneyhubRevenueBy* for dimensional breakdowns. Note: paythrough/flowthrough contract revenue does not appear in standard moneyhub revenue queries - it flows through the adjustment pipeline instead. Check the contract type before querying revenue.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Show revenue by country for account 123", "query": "query ($accountId: ID!, $statementPeriodIdStart: ID) { moneyhubRevenueByCountry(accountId: $accountId, statementPeriodIdStart: $statementPeriodIdStart) { countryCode countryName netRevenuePayeeCurrency grossRevenuePayeeCurrency } }", "variables": { "accountId": "123", "statementPeriodIdStart": "1" } }, { "question": "Top artists by revenue for account 123", "query": "query ($accountId: ID!) { moneyhubRevenueByArtist(accountId: $accountId, limit: 20, orderBy: \"netRevenuePayeeCurrency\", orderDir: \"desc\") { items { artistId artistName netRevenuePayeeCurrency grossRevenuePayeeCurrency } totalRecords } }", "variables": { "accountId": "123" } }, { "question": "Revenue by store for account 123", "query": "query ($accountId: ID!) { moneyhubRevenueByStore(accountId: $accountId, limit: 20, orderBy: \"netRevenuePayeeCurrency\", orderDir: \"desc\") { items { storeId storeName netRevenuePayeeCurrency grossRevenuePayeeCurrency } } }", "variables": { "accountId": "123" } }, { "question": "Revenue by track for account 123", "query": "query ($accountId: ID!) { moneyhubRevenueByTrack(accountId: $accountId, limit: 20, orderBy: \"netRevenuePayeeCurrency\", orderDir: \"desc\") { items { trackName isrc artistName netRevenuePayeeCurrency grossRevenuePayeeCurrency } totalRecords } }", "variables": { "accountId": "123" } }, { "question": "All-time revenue summary for account 123", "query": "query ($accountId: ID!, $statementPeriod: ID!) { moneyhubAllTimeAccountRevenue(accountId: $accountId, statementPeriod: $statementPeriod) { netRevenue grossRevenue currency } }", "variables": { "accountId": "123", "statementPeriod": "1" } } ] }, { "terms": ["expense", "expenses", "account expense", "expense by artist"], "targets": [ "moneyhubExpenses", "moneyhubExpensesPaginated", "moneyhubExpenseUpcs", "moneyhubExpenseArtists", "moneyhubExpenseSubaccounts", "moneyhubExpenseTypes" ], "related": ["MoneyhubExpense", "ReferenceAdjustmentType"], "context": "Expenses tracked against accounts with breakdowns by artist, UPC, subaccount, and type. Key fields: adjustmentAmountPayeeCurrency, adjustmentPayeeCurrencyCode, referenceAdjustmentTypeName, upc, distributionType, applyToStatementPeriodId. Expense types are defined by reference adjustment types. Paginated views support filtering by type, artist, UPC, or subaccount. Use moneyhubExpenses for a summary and moneyhubExpensesPaginated for detailed browsing with filters.", "domain": "revenue", "priority": 1 }, { "terms": [ "account activity", "account statement", "statement balance", "account statements" ], "targets": [ "moneyhubAccountActivity", "moneyhubAccountStatements", "moneyhubAccountActivityPeriods", "accountStatementPeriods" ], "related": [ "MoneyhubAccountActivity", "MoneyhubAccountStatements", "MoneyhubAccountActivityPeriod" ], "context": "Account activity and statement balances showing financial history per account across statement periods. Key fields: statementPeriodId, statementPeriodName, openingBalance, closingBalance, netRevenue, grossRevenue, adjustments, reserves, advances, payments. moneyhubAccountStatements is the primary client-facing statement view with complete financial breakdown per period. moneyhubAccountActivity provides a timeline of all financial events. Use moneyhubAccountStatements for period-over-period financial summaries and moneyhubAccountActivityPeriods for available period ranges.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Show account statements for account 123", "query": "query ($accountId: ID!) { moneyhubAccountStatements(accountId: $accountId, limit: 20, orderDir: \"desc\") { items { statementPeriodId statementPeriodName openingBalance closingBalance netRevenue } totalRecords } }", "variables": { "accountId": "123" } } ] }, { "terms": [ "artist", "participant", "global participant", "contributor", "performer", "tiktok", "shopify", "merch store", "demographics", "social media", "social stats", "marketing program", "performer name", "artist name", "account name", "contract name", "legal name", "stage name", "primary artist", "featuring artist", "session musician", "main performer", "artist lookup", "artist by spotify", "artist by apple music", "artist by social", "artist entity", "knowledge graph artist", "spotify id", "look up artist by spotify id", "artist by id" ], "targets": [ "globalParticipantSearchES", "globalParticipantSearchESxPP", "globalParticipantBySpotifyId", "globalParticipantByAppleMusicId", "globalParticipantByChartmetricId", "globalParticipantBySocialAccountUrl", "globalParticipantByGpId" ], "related": [ "GlobalParticipant", "LabelParticipant", "TiktokAnalytics", "TiktokAggregations", "TiktokScoreByCountry", "Demographics", "DemographicAge", "DemographicGender", "SocialPlatform", "SocialContentType", "SocialFan", "MarketingProgramInfo", "MarketingProgram", "SocialAccountFollowers", "SocialAccountStatV2", "SocialAccountV2Followers", "AggregatedSocialAccountStatV2", "AggregatedParticipantSocialStatV2", "DeltaFollowersValue", "ParticipantSocialData", "PublicParticipant", "PublicSocialAccount", "PublicSocialAccountV2" ], "context": "Participants are artists, performers, or contributors in the global music catalog. Key fields: globalParticipantId, name, spotifyId, appleId, isni, labelParticipantIds. Searchable with streaming stats, social metrics, demographics, and label associations. Each contributor has a Stage Name (the public-facing name, e.g. 'Bob Marley') and a Legal Name (the birth/legal name, e.g. 'Robert Nesta Marley'). Contributor types are: Main Performer (primary credited artist), Featuring Performer (credited but not primary), and Session Musician (uncredited performer). Performers can be found by legal name, stage name, contract name, or account name. Includes TikTok analytics (creation counts, scores by country), Shopify merch store integrations, demographic breakdowns (age, gender), social media metrics (followers, engagement across platforms), and marketing program associations. Use globalParticipantSearchES for general search and globalParticipantSearchESxPP for cross-platform participant search. An artist may be distributed through multiple accounts under the same parent label. Use globalParticipantSearchES to find the artist first, then resolve to account(s) via the participant's label/vendor associations. For direct lookups by platform ID, use: globalParticipantBySpotifyId (Spotify), globalParticipantByAppleMusicId (Apple Music), globalParticipantByChartmetricId (Chartmetric), globalParticipantBySocialAccountUrl (social media URL), globalParticipantByGpId (internal GP ID). These are essential for resolving artist identity across platforms.", "domain": "participant", "priority": 2, "examples": [ { "question": "Search for artist 'Drake'", "query": "query ($term: String) { globalParticipantSearchES(term: $term, limit: 10) { totalCount items { id name } } }", "variables": { "term": "Drake" } }, { "question": "Look up an artist by their Spotify ID and get their name and basic info", "query": "query ($spotifyId: String!) { globalParticipantBySpotifyId(spotifyId: $spotifyId) { id name imageUrl countryCode isPartOfCatalog socialStats { followers monthlyListeners } } }", "variables": { "spotifyId": "5a2EaR3hamoenG9rDuVn8j" } }, { "question": "Look up artist by Spotify ID then get their streaming data", "query": "query ($spotifyId: String!) { globalParticipantBySpotifyId(spotifyId: $spotifyId) { id name analytics { summary(days: 28, breakdown: TOTAL) { items { label value } } timeseries(days: 28) { items { date streams } } } } }", "variables": { "spotifyId": "5a2EaR3hamoenG9rDuVn8j" } } ] }, { "terms": [ "sound recording", "recording", "isrc", "track recording", "recording family", "track", "song", "music track", "cobalt", "contribution id", "legacy id", "recording by isrc", "sound recording by isrc", "isrc lookup" ], "targets": [ "globalSoundRecordingSearchES", "globalSoundRecordingByIsrc", "track", "tracks", "trackSearch" ], "related": [ "GlobalSoundRecording", "GlobalSoundRecordingFamily", "Track" ], "context": "Sound recordings identified by ISRC codes, with streaming stats, associated artists, and label info. Key fields: isrc, title, participantName, duration, labelName, releaseDate, globalSoundRecordingId. Recording families group different ISRC versions of the same recording (e.g., explicit vs. clean, remastered). Tracks are individual songs on a product/release, linked to sound recordings via ISRC. Legacy Cobalt contribution IDs can be used for income searches but not for current ID resolution. Use globalSoundRecordingSearchES to search by ISRC or title and track/tracks for product-level track listings.", "domain": "recording", "priority": 2, "examples": [ { "question": "Search for recording by ISRC", "query": "query ($term: String) { globalSoundRecordingSearchES(term: $term, limit: 10) { totalCount items { isrc title participantName } } }", "variables": { "term": "USAT21301804" } } ] }, { "terms": ["collaborator", "collaboration", "collaborator split", "split"], "targets": ["collaborator"], "related": [ "Collaborator", "CollaboratorTransaction", "CollaboratorsVendorAgreement" ], "context": "Collaborators share royalty splits on releases. Key fields: collaboratorId, productId, splitPercentage, collaboratorName, vendorAgreementId, status. Collaborator splits define how revenue from a release is divided among multiple parties (e.g., featured artist gets 50%, producer gets 10%). Includes transaction tracking for actual split payments, vendor agreements that formalize the split arrangement, and collaborator-specific payee records for payment routing. Use collaborator to view split details for a product.", "domain": "collaborator", "priority": 2, "businessRules": [ "CollaboratorType: COLLABORATOR (external party) | SUBACCOUNT (internal sublabel)", "SplitRateType: GROSS (applied to gross revenue before deductions) | NET (applied to net after deductions) - critical distinction for payout calculations", "Split rates are fractional (0.0-1.0), not percentages (0-100)", "TransactionTypes: BALANCE_CLEARING | CREDIT | DIRECT_PAYMENT | EXPENSE | PAYMENT | PAYMENT_FEES | REVENUE | VOID | WHT_ALLOCATION", "Collaborator statement periods have independent OPEN -> CLOSED lifecycle from Abacus statement periods", "dpEnabled + dpSplitsAgreed flags both must be set to activate direct payment for a collaborator" ], "gotchas": [ "Collaborators use TransferWise/Wise for payments - the batch payment flow is: Profile -> Quote (FX rate lock) -> Recipient -> Batch -> Transfer", "imputedStatus on TransferWise batches is computed by the platform, not raw Wise state - it may differ from the underlying transfer status", "vendorAgreement must be accepted before any collaborator payments can proceed", "performanceRights flag on a collaborator links them to neighbouring rights distributions" ], "relationships": [ "Collaborator -> Track (N:N, via splits - each collaborator has a split rate per track)", "Collaborator -> CollaboratorStatementPeriod (N:N, via participations - financial history per period)", "Collaborator -> TransferWiseBatch (1:N, payment batches with fee breakdown)" ], "examples": [ { "question": "View collaborator splits for a product", "query": "query ($productId: ID!) { collaborator(productId: $productId) { collaboratorId collaboratorName splitPercentage status } }", "variables": { "productId": "5678" } } ] }, { "terms": ["audience", "audience segment", "fan segment", "targeting"], "targets": ["audience", "audiences", "audienceSize"], "related": ["Audience", "AudienceExport"], "context": "Audience segments for marketing and targeting, with export capabilities to Meta and TikTok ad platforms. Key fields: audienceId, name, segmentCriteria, audienceSize, exportStatus, adAccountId. Segments are built from listener demographics, geography, and behavior data. Audiences can be exported to Meta (Facebook/Instagram) and TikTok for advertising campaigns. Meta ad account integration links platform ad accounts for audience sharing. Use audiences to list segments and audienceSize to get estimated reach for a segment.", "domain": "audience", "priority": 2, "businessRules": [ "AudienceFanSegment taxonomy: SUPER_FANS | ENGAGED_FANS | CASUAL_FANS | NEW_FANS | FANS_TO_WIN_BACK | SECONDARY_FANS | UNSEGMENTED_FANS", "AudienceTarget: ADS | EMAIL | TEXT - determines which consent counts and export destinations are valid", "AudienceExportReason: ADS_GOOGLE | ADS_META | ADS_SNAPCHAT | ADS_SPOTIFY | ADS_TIKTOK | EMAIL_SALESFORCE | TEXT_COMMUNITY | TEXT_LAYOUT", "Fan consent is tracked independently at three levels: ad consent, email consent, SMS consent - counts differ substantially" ], "gotchas": [ "fansCount includes fans without any consent; use the consent-scoped count (adConsentFansCount, emailConsentFansCount, smsConsentFansCount) for the campaign type", "availableFansShare in demographic stats indicates what fraction of fans have DSP data - percentages apply to the available subset, not total fans", "includeSecondaryFans toggles whether fans of labelmates are included - dramatically changes audience size", "Heavy rotation is a streaming engagement signal from DSPs (IN | NOT_IN | UNKNOWN), not a self-reported preference", "Text campaigns auto-cancel with cancelReason NO_FANS if no fans match the audience at send time" ], "examples": [ { "question": "List audience segments", "query": "query { audiences(limit: 20) { items { audienceId name audienceSize exportStatus } totalCount } }", "variables": {} } ] }, { "terms": [ "chart", "chart ranking", "chart position", "top songs", "top artists", "shazam", "shazam chart", "billboard", "new music friday", "chart entry", "chart debut", "charts", "chart rankings", "chart positions", "top 200", "top 100", "viral 50", "viral 100", "viral chart", "chart v2", "chart group", "chart platform", "new music friday chart", "what charts is this on", "chart history", "chart trend", "daily chart", "weekly chart", "chart placement", "chart peak", "chart streak", "streak length", "soundcloud chart", "tiktok chart", "youtube chart", "line music chart", "recochoku chart", "itunes chart", "chart position over time" ], "targets": [ "chartRankingsV2", "topGlobalSoundRecordings", "topChannels", "topVideos", "chartsV2", "chartsV2ByDefinition", "chartsV2GroupBySlug" ], "related": [ "ChartRankingV2", "ChartV2", "ChartV2Group", "ChartV2Date", "ChartV2DatePlacementResult", "ChartV3DatePlacementResult", "ChartRankingV3", "ChartByPlatform", "ChartsByPlatformsResults", "ChartFacetsV2", "PlatformChart", "PlatformChartPlacement", "PlatformChartCountryPlacement", "NewMusicFridayDateMarket" ], "context": "Chart rankings and top-performing content across streaming platforms. Use chartsV2ByDefinition for specific chart lookups with filtering by platform (spotify, apple_music, shazam, deezer, youtube, amazon, tiktok, soundcloud, line_music, recochoku, itunes), target (tracks, albums, videos), frequency (daily, weekly), countryCode, type, and genre. CHART TYPES: Spotify - Daily Top 200, Weekly Top 200, Daily Viral 100; Apple Music - Daily Top 100 per country; Deezer - Daily Top 100; Shazam - Daily Top Tracks (200); YouTube - Top Songs (weekly, 100), Top Videos (weekly, 100); Amazon - Top Tracks; TikTok - All Time Top Tracks (daily, 1000), Weekly Top Tracks; SoundCloud - Daily Top Tracks (200), Daily New & Hot; LINE Music (Japan) - Daily/Weekly Top 100; Recochoku (Japan) - Daily/Weekly Top 200; iTunes - Daily Top Albums. Each chart date has placements with position, previousPosition, positionChange, streakLength. ChartRankingV2/V3 include sound recording, product, and artist info. To check what charts a song is on, use chartRankingsV2 filtered by ISRC. For daily position history, fetch multiple dates. Note: Users often confuse playlists (like 'Amazon Daily Pop') with charts - playlists should be queried via playlist endpoints, not chart endpoints.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Get Spotify daily top tracks chart for the US", "query": "query { chartsV2ByDefinition(platform: \"spotify\", target: \"tracks\", frequency: \"daily\", countryCode: \"US\") { chartId chartName dates(limit: 1) { date placements(limit: 20) { position previousPosition positionChange soundRecording { name isrc } } } } }", "variables": {} }, { "question": "Daily chart position for a song over a date range", "query": "query { chartsV2ByDefinition(platform: \"spotify\", target: \"tracks\", frequency: \"daily\", countryCode: \"GLOBAL\") { chartId chartName dates(startDate: \"2026-02-02\", endDate: \"2026-02-05\") { date placements(filter: { isrc: \"USAT21301804\" }) { position previousPosition positionChange streakLength soundRecording { name isrc } } } } }", "variables": {} }, { "question": "What charts a track appears on across all platforms", "query": "query ($isrc: String!) { chartRankingsV2(chartId: \"spotify_daily_tracks_global\", chartDate: \"2026-01-01\", limit: 50) { chartName position previousPosition positionChange soundRecording { name isrc } } }", "variables": { "isrc": "USAT21301804" } }, { "question": "Shazam daily chart for a specific country", "query": "query { chartsV2ByDefinition(platform: \"shazam\", target: \"tracks\", frequency: \"daily\", countryCode: \"ES\") { chartId chartName dates(limit: 1) { date placements(limit: 20) { position soundRecording { name isrc } } } } }", "variables": {} } ] }, { "terms": ["video", "music video", "ugc", "channel"], "targets": ["video", "videoCatalogSearch", "channel", "channels"], "related": ["Video", "Channel", "UgcVideoMetricsResults"], "context": "Video content including music videos and UGC (user-generated content), organized by channels. Key fields: videoId, title, channelId, viewCount, uploadDate, ugcClaimCount. UGC metrics track user-generated video performance and revenue from content ID claims. Channels group videos under a single creator or label. Use videoCatalogSearch to find videos and channels to browse channel listings.", "domain": "video", "priority": 1 }, { "terms": [ "playlist", "playlist placement", "playlisting", "on playlist", "added to playlist", "removed from playlist", "playlist adds", "editorial playlists entered", "playlist position", "days on playlist", "playlist type" ], "targets": ["playlist", "playlistPlacement", "playlistPlacements"], "related": ["Playlist", "PlaylistPlacement"], "context": "Playlist placements track where songs appear on streaming platform playlists. Key fields: playlistId, playlistName, storeName, storeId, followerCount, trackPosition, currentPosition, previousPosition, peakPosition, positionChange, daysOnPlaylist, addedDate, removedDate, playlistType (CURATED, EDITORIAL, PERSONALIZED, ALGORITHMIC, STATION, RADIO). Playlisting is a key driver of streaming volume. For editorial playlists entered after a date, filter by playlistType EDITORIAL and addedDate >= date. Note: Users often confuse playlists with charts - 'Amazon Daily Pop' is a playlist, not a chart. Use playlistPlacements to see all current and historical placements for a track or artist.", "domain": "playlist", "priority": 3, "examples": [ { "question": "Current playlist placements for a track", "query": "query ($isrc: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { playlistPlacements { placements { playlistName storeName followerCount currentPosition peakPosition daysOnPlaylist playlistType addedDate } totalCount } } }", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "event", "abacus event", "workflow event", "audit trail", "workflow state", "action status", "state machine", "approval status" ], "targets": ["abacusEvents", "abacusState", "abacusStateById"], "related": ["AbacusEvent", "AbacusState"], "context": "Events are immutable audit log entries tracking domain actions like payment approvals, file uploads, and state transitions. Key fields: eventId, entityType, entityId, eventType, userId, createdAt, payload. The state machine tracks action statuses (INIT, RUNNING, ERROR, COMPLETE, APPROVED, REJECTED) across entities like accounting runs, payment groups, and file uploads. Every significant domain action produces an event for traceability. Use abacusEvents to query the audit trail and abacusState/abacusStateById to check current entity status.", "domain": "events", "priority": 1 }, { "terms": [ "schedule", "contributor schedule", "abacus schedule", "recording bucket", "performer schedule", "which schedule does a song belong to" ], "targets": ["abacusSchedule"], "related": ["AbacusSchedule", "ScheduleAttachment"], "context": "Schedules are buckets of recordings associated with contracts in Abacus. Each schedule groups recordings under a contract. A performer can have multiple schedules across different contracts. Key fields: scheduleId, contractId, participantId, recordings, status. Schedules are auto-created when contract parties are added. Use to find which schedule a specific song belongs to, or which contract a schedule is attached to. Use abacusSchedule filtered by accountId to list all schedules for a performer.", "domain": "schedule", "priority": 2, "examples": [ { "question": "Which of Ed Sheeran's schedules does Perfect belong to", "query": "query ($accountId: Int) { abacusSchedule(accountId: $accountId) { scheduleId contractId recordings { title isrc } } }", "variables": { "accountId": "12345" } } ] }, { "terms": ["file upload", "upload file", "import file"], "targets": [ "abacusFileUpload", "abacusFileUploadDownload", "abacusUploadToken" ], "related": ["AbacusFileUploadDetail"], "context": "File uploads support multipart S3 uploads for adjustments, payment approvals, and custom payments. Key fields: fileUploadId, fileName, fileType, fileSize, status, uploadedBy, uploadedAt, s3Key. Statuses: INIT -> SCANNING -> COMPLETE | ERROR. Upload tokens provide temporary S3 credentials for direct-to-S3 multipart upload. File types include adjustment files, payment approval files, and custom payment files. Use abacusFileUpload to check upload status and abacusUploadToken to get upload credentials.", "domain": "files", "priority": 1 }, { "terms": ["download", "export", "download report", "vat report"], "targets": ["abacusDownload"], "related": ["AbacusDownload"], "context": "Downloads provide export URLs for reports, VAT summaries, adjustment templates, and other generated files. Key fields: downloadId, downloadType, status, url, expiresAt, generatedAt. Download types include: accounting_run_summary, payment_approval, custom_report, statement_attachment, vat_report, adjustment_template. URLs are pre-signed S3 links with expiration. Use abacusDownload to generate and retrieve download links for various report types. For data-heavy exports with wide tables (many columns), recommend Excel or CSV format over PDF. PDF rendering truncates wide tables and causes column overflow. When generating reports, prefer tabular formats for detailed data and PDF only for summary views.", "domain": "files", "priority": 1 }, { "terms": [ "content review", "review queue", "approve content", "reject content" ], "targets": ["product"], "related": ["ReviewQueueItem"], "context": "Content review manages approval workflows for products and releases before distribution. Key fields: reviewItemId, productId, reviewStatus, assignedTo, submittedAt, reviewedAt, reviewNotes. Review statuses flow: SUBMITTED -> IN_REVIEW -> APPROVED | REJECTED | NEEDS_CHANGES. Products must pass content review before they can be delivered to stores. Use product queries filtered by review status to manage the review queue.", "domain": "content-review", "priority": 1 }, { "terms": [ "nr contribution", "nr delivery", "neighbouring rights delivery", "nr contributor", "ownership nr", "nr delivery orders", "neighbouring rights delivery orders", "nr contributions delivery", "neighbouring rights contribution" ], "targets": ["nrContributions", "nrContributors", "nrDeliveryOrders"], "related": [ "NrContribution", "NrContributor", "NrDeliveryOrder", "OwnershipNrProduct", "OwnershipNrSoundRecording" ], "context": "Neighbouring rights contributions and contributors are delivered to collection societies via delivery orders and jobs. Key fields: contributionId, contributorId, isrc, performerRole, deliveryOrderId, deliveryStatus, collectionSociety, territory. Ownership NR tracks ownership-based neighbouring rights at product and recording level. Delivery orders batch contributions for submission to societies like PPL, GVL, and SENA. Use nrContributions to view contribution details and nrDeliveryOrders to track delivery status.", "domain": "neighbouring-rights", "priority": 1 }, { "terms": [ "signing entity", "payment entity", "legal entity", "reference entity" ], "targets": [ "abacusReferenceSigningEntity", "abacusReferenceSigningEntities", "abacusReferencePaymentEntity", "abacusReferencePaymentEntities" ], "related": [ "AbacusReferenceSigningEntity", "AbacusReferencePaymentEntity" ], "context": "Signing entities are legal entities that sign contracts (e.g., AWAL-UK, KNR-UK, ORCHARD-ES). Payment entities receive and process payments on behalf of the company. Key fields: entityId, entityName, entityCode, country, currency, isActive. Both are reference data lookups used when creating contracts and configuring payment terms. Every contract has a signing entity; every payment term has a payment entity. Use abacusReferenceSigningEntities to list all signing entities and abacusReferencePaymentEntities for payment entities. The list endpoint returns every entity in one response (no pagination, no name filter); substring-match client-side on legalName to resolve a name from a PDF or other source to a referenceSigningEntityId.", "domain": "reference", "priority": 1, "examples": [ { "question": "List all signing entities to resolve a name like 'Sony Music UK' to its referenceSigningEntityId", "query": "query AbacusReferenceSigningEntities { abacusReferenceSigningEntities { items { referenceSigningEntityId legalName companyCode address companyRegistrationNumber vatNumber } } }", "variables": {} }, { "question": "Fetch a single signing entity by ID", "query": "query ($referenceSigningEntityId: ID!) { abacusReferenceSigningEntity(referenceSigningEntityId: $referenceSigningEntityId) { referenceSigningEntityId legalName companyCode address } }", "variables": { "referenceSigningEntityId": "42" } } ] }, { "terms": ["vendor", "label", "record label", "subaccount"], "targets": ["abacusAccounts"], "related": ["Vendor", "Subaccount", "Label", "CompanyBrand"], "context": "Vendors are music labels/distributors represented as accounts in Abacus. Key fields: vendorId (= accountId), vendorName, subaccountId, labelId, companyBrandId. Subaccounts are subdivisions under a vendor for organizational grouping (e.g., different imprints). Company brands group multiple vendor accounts under a parent entity (e.g., AWAL, Sony). Labels represent the record label identity on releases. Use abacusAccounts with search filters to find vendors, labels, or subaccounts. The owner field distinguishes Sony business units: Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR (Kollective Neighbouring Rights), etc. Each has its own operational processes. Filter by owner to scope queries to a specific business unit.", "domain": "account", "priority": 1 }, { "terms": [ "mechanical deduction", "mechanical royalty", "mechanical rate" ], "targets": [ "abacusContractMechanicalDeduction", "abacusContractMechanicalDeductions", "abacusReferenceMechanicalRates" ], "related": [ "AbacusContractMechanicalDeduction", "AbacusReferenceMechanicalRate" ], "context": "Mechanical deductions are royalty deductions for mechanical rights by territory (USA, CAN, ROW) and type (digital, physical). Key fields: deductionId, contractId, territory, mechanicalType, rate, effectiveDate. Mechanical rights compensate songwriters/publishers for reproduction of their compositions. Reference mechanical rates provide statutory US rates set by the Copyright Royalty Board. Deductions are applied during accounting runs to reduce gross revenue by the applicable mechanical rate. Use abacusContractMechanicalDeductions to view deductions for a contract and abacusReferenceMechanicalRates for current statutory rates.", "domain": "royalties", "priority": 1 }, { "terms": [ "accounting run", "royalty calculation", "calculate royalties", "run results", "run controller", "accounting batch", "contract grouping" ], "targets": [ "abacusAccountingRun", "abacusAccountingPeriodReport", "abacusRunControllers" ], "related": [ "AbacusAccountingRun", "AbacusAccountingPeriodReport", "AbacusRunController" ], "context": "Accounting runs execute royalty calculations for contracts within an accounting period. Key fields: accountingRunId, accountingPeriodId, runStatus, contractType, startedAt, completedAt, contractCount, totalRevenue. Run statuses: INIT -> RUNNING -> COMPLETE | ERROR. Each run matches contract terms to sales data and computes revenue per contract. Reports summarize run results with totals and breakdowns. Run controllers group contracts for accounting runs, determining which contracts participate in each royalty calculation batch. Use abacusAccountingRun for run details and abacusRunControllers for batch configuration. abacusRunControllers is paginated (required limit + offset) and supports optional accountId and contractType filters but has no name search; to resolve a run controller name to a runControllerId (e.g. when assigning a new contract to a run group during create_contract), page through 100 at a time and substring-match client-side on runControllerName.", "domain": "accounting", "priority": 2, "examples": [ { "question": "Get details for accounting run 789", "query": "query ($accountingRunId: ID) { abacusAccountingRun(accountingRunId: $accountingRunId) { accountingRunId accountingPeriodId runStatus contractType startedAt completedAt } }", "variables": { "accountingRunId": "789" } }, { "question": "List run controllers to resolve a name like 'Distribution' to its runControllerId (first page; increment offset by 100 to scan further)", "query": "query AbacusRunControllers($limit: Int!, $offset: Int!) { abacusRunControllers(limit: $limit, offset: $offset) { items { runControllerId runControllerName contractType } } }", "variables": { "limit": 100, "offset": 0 } }, { "question": "List run controllers filtered by contractType (still paginated)", "query": "query AbacusRunControllers($contractType: String, $limit: Int!, $offset: Int!) { abacusRunControllers(contractType: $contractType, limit: $limit, offset: $offset) { items { runControllerId runControllerName contractType } } }", "variables": { "contractType": "distribution", "limit": 100, "offset": 0 } } ] }, { "terms": [ "transaction type", "stream type", "download type", "consumption type", "revenue type" ], "targets": [ "transactionType", "transactionTypes", "transactionTypeGroups" ], "related": [ "TransactionType", "TransactionTypeGroup", "TransactionTypeGroupAdmin" ], "context": "Transaction types classify consumption types: stream, download, radio, physical, sync, ringtone, and more. Key fields: txnTypeId, name, groupId, isActive. Groups organize types into categories for different contexts: contract terms (which types a rate applies to), mechanicals (which types incur mechanical deductions), tax (which types are taxable), and reporting (how types appear in revenue breakdowns). Use transactionTypes to list all types and transactionTypeGroups for grouped views.", "domain": "reference", "priority": 2, "examples": [ { "question": "List all transaction types", "query": "query { transactionTypes { txnTypeId name } }", "variables": {} } ] }, { "terms": [ "account balance", "payable balance", "current balance", "how much is owed", "positive balance", "positive ledger balance", "what's our balance", "how much do we owe", "positive ledger balances" ], "targets": ["abacusAccountPayableBalance", "abacusAccountCurrentBalance"], "related": ["AbacusAccountPayableBalance", "AbacusAccountCurrentBalance"], "context": "Account balances show the current payable amount and overall balance for a vendor account across all contracts. Key fields: accountId, payableAmount, currentBalance, currencyCode, lastCalculatedAt. Payable balance is the amount eligible for payment (after reserves, holds, minimums). Current balance is the running total of all ledger entries. The difference between current and payable typically reflects reserves held, pending adjustments, or payment holds. Use abacusAccountPayableBalance for payment-eligible amounts and abacusAccountCurrentBalance for the full running total.", "domain": "ledger", "priority": 2, "examples": [ { "question": "What is the payable balance for account 123?", "query": "query ($accountId: ID!) { abacusAccountPayableBalance(accountId: $accountId) { amount currencyCode } }", "variables": { "accountId": "123" } } ] }, { "terms": [ "adjustment file", "adjustment import", "batch adjustment", "adjustment upload" ], "targets": [ "abacusStatementPeriodAdjustmentFile", "abacusStatementPeriodAdjustmentFiles", "abacusStatementPeriodAdjustmentFilesList", "abacusStatementPeriodAdjustmentBatchCriteria" ], "related": [ "AbacusStatementPeriodAdjustmentFile", "AbacusStatementPeriodAdjustmentBatchCriteriaDetail" ], "context": "Adjustment files are uploaded to statement periods for batch processing of royalty corrections. Key fields: adjustmentFileId, statementPeriodId, fileName, rowCount, status, uploadedBy, importedAt. Lifecycle: UPLOAD -> VALIDATE -> IMPORT -> APPLY. Batch criteria define filtering rules for which adjustments to apply (by account, contract, or type). Failed rows are reported with error details for correction and re-upload. Use abacusStatementPeriodAdjustmentFiles to list uploaded files and their status.", "domain": "adjustments", "priority": 1 }, { "terms": [ "vat", "value added tax", "vat rate", "vat summary", "vat calculation" ], "targets": [ "abacusLedgerAccountingRunVat", "abacusLedgerAccountingRunVatOverview", "abacusReferenceVatRates", "moneyhubPaymentEntityVat" ], "related": [ "AbacusLedgerAccountingRunVat", "AbacusLedgerAccountingRunVatOverview", "AbacusReferenceVatRatesList" ], "context": "VAT is calculated per accounting run with details by contract and territory. Key fields: vatId, accountingRunId, contractId, territory, vatRate, vatAmount, netAmount, grossAmount. Reference VAT rates provide applicable rates by country and transaction type. VAT is applied to royalty payments for EU and other jurisdictions that require it. Payment entity VAT data via moneyhub shows VAT totals per payment entity for reporting. Use abacusLedgerAccountingRunVat for per-run VAT details and abacusReferenceVatRates for rate lookups.", "domain": "tax", "priority": 1 }, { "terms": [ "statement attachment", "statement report", "distribution statement", "invoice", "vat invoice", "revenue detail report", "collection summary", "download statement" ], "targets": ["moneyhubStatementAttachments", "moneyhubStatementInvoices"], "related": ["MoneyhubStatementAttachment", "MoneyhubStatementInvoice"], "context": "Statement attachments are PDF/Excel documents generated per statement period. Key fields: attachmentId, statementPeriodId, attachmentType, fileName, downloadUrl, generatedAt. Attachment types: revenue_detail_report, collection_summary, payment_summary. Invoices are generated per payment entity and statement period for accounting and tax purposes. Use moneyhubStatementAttachments to list available documents and download URLs for a given statement period.", "domain": "revenue", "priority": 1 }, { "terms": [ "ledger adjustment", "applied adjustment", "moneyhub adjustment" ], "targets": [ "moneyhubLedgerAdjustments", "moneyhubLedgerAdjustmentTypes", "abacusLedgerAdjustments" ], "related": ["MoneyhubLedgerAdjustment", "ReferenceAdjustmentType"], "context": "Ledger adjustments are corrections applied at the ledger level, distinct from worksheet adjustments which are pre-approval. Key fields: ledgerAdjustmentId, accountId, contractId, amount, currencyCode, adjustmentType, statementPeriodId, appliedAt. Moneyhub provides the client-facing view of applied adjustments with available adjustment types for filtering. Use moneyhubLedgerAdjustments to view applied adjustments for an account and moneyhubLedgerAdjustmentTypes for the available type filter list.", "domain": "ledger", "priority": 1 }, { "terms": [ "reference data", "agreement type", "payment type", "payoneer program", "exchange rate", "currency conversion", "forex" ], "targets": [ "abacusReferenceAgreementTypes", "abacusReferencePaymentTypes", "abacusPayoneerPrograms", "abacusReferenceTaxWithholding", "abacusExchangeRates" ], "related": [ "AbacusReferenceAgreementType", "AbacusReferencePaymentType", "AbacusReferencePayoneerProgram", "AbacusReferenceTaxWithholding", "AbacusExchangeRates" ], "context": "Reference data includes agreement types (distribution deal types like STANDARD, CUSTOM, SERVICES), payment types (Payoneer, SAP, wire transfer), Payoneer program configurations, tax withholding rates by country, and exchange rates. Key fields vary by type. Exchange rates are uploaded per statement period for multi-currency royalty calculations - each period has a snapshot of rates used to convert foreign currency revenue to the account's payment currency. Use abacusReferenceAgreementTypes, abacusReferencePaymentTypes, and abacusPayoneerPrograms for dropdown lookups, and abacusExchangeRates for currency conversion rates.", "domain": "reference", "priority": 1 }, { "terms": ["project", "release project", "project code"], "targets": ["moneyhubProjectsByAccount"], "related": ["MoneyhubProject", "Project"], "context": "Projects group related releases under a project code for organizational and reporting purposes. Key fields: projectId, projectCode, projectName, accountId, releaseCount, totalRevenue. Projects allow vendors to organize their catalog into logical groupings (e.g., by album campaign, by artist) and view aggregated revenue across all releases in a project. Use moneyhubProjectsByAccount to list projects for an account.", "domain": "product", "priority": 1 }, { "terms": [ "podcast", "podcasts", "podcast network", "show", "episode", "podcast episode" ], "targets": [ "podcast", "podcasts", "podcastNetwork", "podcastNetworks", "episode", "episodes" ], "domain": "podcast", "priority": 1 }, { "terms": ["ad read", "podcast ad", "host read ad", "podcast advertising"], "targets": ["podcast"], "related": ["AdRead", "AdReadComment"], "context": "Ad reads track podcast host-read advertisements with commenting and approval workflows. Key fields: adReadId, podcastId, episodeId, advertiserName, adCopy, status, submittedAt, approvedAt. Ad read statuses: DRAFT -> SUBMITTED -> APPROVED | REJECTED. Comments enable feedback between sales teams and podcast hosts. Use podcast queries to access ad read details for a show.", "domain": "podcast", "priority": 1 }, { "terms": [ "product search", "search products", "find release", "find album" ], "targets": ["globalProductSearchES"], "related": ["Product"], "context": "Global product search via Elasticsearch. Search for music releases (albums, singles, EPs) by title, UPC, or artist name. Returns product metadata including release date, label, and track listing. Key fields: id, title, upc, artistName, releaseDate, labelName, trackCount, productType. Use for finding specific releases or browsing catalog. Faster than the product query for search-style lookups.", "domain": "product", "priority": 2, "examples": [ { "question": "Search for the album 'Divide'", "query": "query ($query: String!, $limit: Int) { globalProductSearchES(query: $query, limit: $limit) { results { id title upc artistName releaseDate } totalCount } }", "variables": { "query": "Divide", "limit": "10" } } ] }, { "terms": [ "artists by account", "imprints by account", "recordings by account", "stores by account", "tracks by account", "transaction types by account", "account dimensions", "account lookups" ], "targets": [ "moneyhubArtistsByAccount", "moneyhubImprintsByAccount", "moneyhubRecordingsByAccount", "moneyhubStoresByAccount", "moneyhubTracksByAccount", "moneyhubTransactionTypesByAccount" ], "context": "Helper queries that return dimension values scoped to a specific account. Used to populate filter dropdowns in revenue reports - get the list of artists, imprints, recordings, stores, tracks, or transaction types that have data for a given accountId. Key fields vary by dimension (e.g., artistId/artistName for artists, storeId/storeName for stores). All accept accountId as the primary filter. Use these before revenue queries to build valid filter options for the user.", "domain": "revenue", "priority": 1 }, { "terms": [ "label search", "find label", "label lookup", "orchard label", "imprint", "sub-label", "vendor contact", "master contact", "label contact" ], "targets": [ "orchardLabel", "orchardLabels", "orchardLabelSearch", "vendor" ], "related": ["OrchardLabel"], "context": "Orchard label search and vendor contact lookup. orchardLabelSearch provides text search across the OA label catalog (distinct from abacusAccounts). orchardLabel returns label details by vendor ID. The vendor query returns master contact info.", "domain": "account", "priority": 2 }, { "terms": [ "custom payment", "one-off payment", "manual payment", "ad hoc payment" ], "targets": ["customPayment", "customPayments"], "context": "Custom payments are one-off, ad-hoc payments made outside the regular payment group batch process. Used for special disbursements, corrections, or manual payouts that don't fit the standard payment cycle. Custom payments have their own reports and event tracking.", "domain": "payments", "priority": 2 }, { "terms": [ "qualified advance", "advances ready for approval", "advance approval queue" ], "targets": ["abacusContractAdvancesQualified"], "context": "Qualified advances have met their milestone conditions and are ready for approval before payment. This is a distinct lifecycle stage between NOT_QUALIFIED and APPROVED.", "domain": "advances", "priority": 2 }, { "terms": [ "advance deduction", "advance recoup from payment", "recoup advance", "advance in payment worksheet" ], "targets": [ "worksheetPaymentContractAdvance", "worksheetPaymentContractAdvances" ], "context": "Worksheet payment contract advances track how advances are recouped (deducted) from regular payment batches. When a payment is processed, outstanding advances are deducted from the payable amount.", "domain": "advances", "priority": 2 }, { "terms": [ "flowthrough formula", "flowthrough calculation", "flowthrough rate calculation", "how is flowthrough calculated" ], "targets": [ "abacusReferenceFlowthroughCalculation", "abacusReferenceFlowthroughCalculations" ], "related": ["AbacusReferenceFlowthroughCalculation"], "context": "Reference flowthrough calculations define the four formulas used to compute flowthrough amounts: (1) (Net Revenue x Rate) + Expenses, (2) (Net Revenue + Expenses) x Rate, (3) Net Revenue x Rate, (4) Gross Revenue x Rate.", "domain": "flowthrough", "priority": 2 }, { "terms": ["upc lookup", "find by upc", "product by upc"], "targets": ["productByUpc", "searchProducts", "allProductsSearch"], "context": "Direct product lookup by UPC barcode or free-text product search. productByUpc returns a single product matching a UPC. searchProducts and allProductsSearch provide catalog-wide text search across titles, UPCs, and artist names.", "domain": "product", "priority": 2 }, { "terms": ["payee list", "list payees", "all payees", "payee directory"], "targets": ["abacusPayees"], "context": "Bulk payee listing across accounts. Unlike abacusAccountPayee which returns payee info for a single account, abacusPayees returns a paginated list of all payees with payment method, eligibility, and account associations.", "domain": "payee", "priority": 2 }, { "terms": [ "collaborator payment", "distribution partner payment", "split payment", "dp payment" ], "targets": ["dpPayments"], "related": ["DpPayment"], "context": "Distribution partner (DP) payments track actual split payment amounts disbursed to collaborators for a given statement period. Distinct from collaborator splits (which define percentages) - dpPayments shows realized payment amounts after royalty calculation.", "domain": "collaborator", "priority": 2 }, { "terms": [ "account ledger history", "ledger by account", "all ledger entries for account" ], "targets": ["abacusAccountLedgerList"], "context": "Account-scoped ledger history showing all financial entries for a specific account. Similar to abacusLedgerAccountContractList but scoped at the account level. Returns chronological ledger entries with event names, amounts, and statement periods.", "domain": "ledger", "priority": 2 }, { "terms": [ "search nr contributors", "find nr contributor", "nr contributor search", "contributor lookup" ], "targets": [ "nrContributorSearch", "nrContributionById", "nrContributorById" ], "context": "Search and lookup for neighbouring rights contributors. nrContributorSearch provides text search across NR contributors. nrContributorById and nrContributionById return specific records by ID.", "domain": "neighbouring-rights", "priority": 2 }, { "terms": [ "pending payment accounts", "accounts pending in payment", "payment run pending accounts" ], "targets": ["abacusPendingPaymentGroupPaymentAccounts"], "context": "Lists accounts with pending status within a payment group payment batch. Shows which vendor accounts are awaiting processing or have issues blocking payment completion.", "domain": "payments", "priority": 2 }, { "terms": [ "flowthrough batch", "flowthrough worksheet batch", "process flowthrough" ], "targets": ["abacusWorksheetFlowthroughBatch"], "context": "Flowthrough worksheet batches group flowthrough payment calculations for bulk processing within a statement period. Each batch contains the computed flowthrough amounts for contracts with active flowthrough configurations. Use abacusWorksheetFlowthroughBatch to view batch details and processing status.", "domain": "flowthrough", "priority": 2 }, { "terms": [ "ledger balance by period", "statement period ledger balance", "ledger by statement period", "period balance breakdown" ], "targets": ["abacusLedgerAccountStatementPeriod"], "context": "Statement period ledger balances show the aggregated financial position per account and contract for a specific statement period. Distinct from the general ledger entry list - this provides period-level balance summaries rather than individual transactions.", "domain": "ledger", "priority": 2 }, { "terms": [ "payment entities for period", "statement period payment entities", "which entities pay this period", "active payment entities" ], "targets": ["abacusStatementPeriodPaymentEntities"], "context": "Lists the payment entities active for a given statement period. Payment entities are the legal entities that process payments (e.g., The Orchard Enterprises, AWAL Digital). Each statement period may have different active entities based on business operations. Use to determine which entities are processing payments for a period.", "domain": "payments", "priority": 2 }, { "terms": [ "payment minimum", "minimum payment", "payment threshold", "minimum balance for payment" ], "targets": ["abacusPaymentMinimum", "abacusPaymentMinimums"], "context": "Payment minimums define the minimum balance required before a payment is issued to a vendor. If an account's payable balance is below the minimum, payment is deferred to the next cycle. Minimums are configured per currency. Use abacusPaymentMinimum for a specific currency and abacusPaymentMinimums for all configured minimums.", "domain": "payments", "priority": 2 }, { "terms": [ "payment term", "payment schedule", "payment frequency", "net 30", "net 45", "net 60", "net 90", "payment interval" ], "targets": ["abacusAccountPaymentTerm"], "context": "Payment terms define when and how a vendor gets paid: payment schedule (30/45/60/90 days after month/quarter/half-year end), currency, and payment entity. Each account has payment terms that determine the frequency and timing of royalty disbursements.", "domain": "payments", "priority": 2 }, { "terms": [ "revenue by statement period", "revenue by period", "period revenue trend" ], "targets": ["moneyhubRevenueByStatementPeriod"], "context": "Revenue aggregated by statement period for trend analysis. Shows net and gross revenue per accounting cycle. Use for period-over-period comparisons.", "domain": "revenue", "priority": 2 }, { "terms": [ "streaming analytics", "track streams", "artist streams", "product streams", "streaming performance", "top tracks", "top accounts", "streaming leaderboard", "sound recording streams", "album streams", "label streams", "total streams", "highest streams", "most streams", "best performing", "top performing", "streams by dsp", "streams by brand", "streams", "compare streams" ], "targets": ["topGlobalSoundRecordingFamilies", "topAccounts"], "related": [ "GlobalSoundRecordingFamilyResults", "GlobalSoundRecordingFamilyAnalytics", "AccountResults", "GlobalParticipantAnalytics", "GlobalParticipantAnalyticsSummary", "GlobalParticipantAnalyticsTimeseries", "GlobalSoundRecordingAnalytics", "ProductAnalytics", "SubaccountAnalytics", "VendorAnalytics", "TrackAnalytics", "SourceOfStreams", "StreamsBySourceOfStreams", "StreamSource", "StreamSourceFilter", "AggregatedSummaryBySOS", "AggregatedSummaryBySOSItem", "SoundRecordingPeakStreams" ], "context": "Streaming analytics queries powered by ows-analytics. topGlobalSoundRecordingFamilies returns ranked sound recordings with stream counts (1-day, 7-day, 28-day, all-time) and growth percentages. Supports filtering by label_ids, subaccount_ids, store_ids, countries, and company_brand. topAccounts returns ranked accounts (labels) by streaming performance. Analytics types on entities include summary (breakdowns: SOS, SOS_DETAILED, COUNTRY, STORE, TOTAL, PRODUCT, ACTIVE_TOTALS, PASSIVE_TOTALS) and timeseries sub-fields. Summary breakdown types: SOS returns active/passive/collection aggregates; SOS_DETAILED returns per-DSP source breakdown (Spotify: collection, playQueue, albumPage, artistPage, search, playlists, releaseRadar, discoverWeekly, radio, dailyMix, chart; Apple: library, external, voice, search, musicKit, nowPlaying, discovery; Amazon: userPlaylist, songs, album, artist, search, playlist, station; YouTube: browseFeatures, directOrUnknown, suggestedVideos, youtubeSearch, playlists). Timeseries items include: streams, skipRate (Float), skips (Long), saves (Long), downloads, trackDownloads, albumDownloads. Use streamSources filter on summary/timeseries to filter by source type. Key StreamSourceFilter values: ARTIST, SEARCH, COLLECTION, LIBRARY, PLAYLIST, RELEASERADAR, DISCOVERWEEKLY, RADIO, BROWSE_FEATURES, CHART. For 'streams by brand/DSP', use summary with STORE breakdown. For period comparisons, use startDate + days parameters - response includes value, prevValue, growthPercentage for each period.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Top 10 tracks by 28-day streams for a label", "query": "query ($filter: GlobalSoundRecordingFamilyAnalyticsFilterInput!) { topGlobalSoundRecordingFamilies(filter: $filter, pagination: { limit: 10, orderBy: \"streams_28_days\", orderDir: \"DESC\" }) { items { name isrc streams28Days streams7Days growthPct } totalCount } }", "variables": { "filter": "{ \"labelIds\": [1234] }" } }, { "question": "Source of streams breakdown for a track (detailed per-DSP)", "query": "query ($isrc: String!, $startDate: String!, $days: Int!) { globalSoundRecordingByIsrc(isrc: $isrc) { analytics { summary(startDate: $startDate, days: $days, breakdown: SOS_DETAILED) { items { label value } } } } }", "variables": { "isrc": "USAT21301804", "startDate": "2026-01-01", "days": 28 } }, { "question": "Streams by DSP/store for a track with date range", "query": "query ($isrc: String!, $startDate: String!, $days: Int!) { globalSoundRecordingByIsrc(isrc: $isrc) { analytics { summary(startDate: $startDate, days: $days, breakdown: STORE) { items { label value prevValue growthPercentage } } } } }", "variables": { "isrc": "USAT21301804", "startDate": "2026-01-01", "days": 28 } }, { "question": "Daily stream timeseries for a track with skip rate and saves", "query": "query ($isrc: String!, $startDate: String!, $endDate: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { analytics { timeseries(startDate: $startDate, endDate: $endDate) { items { date streams skipRate skips saves } } } } }", "variables": { "isrc": "USAT21301804", "startDate": "2026-01-25", "endDate": "2026-01-28" } }, { "question": "Total streams by brand including specific artists (multi-artist filter)", "query": "query ($filter: GlobalSoundRecordingFamilyAnalyticsFilterInput!) { topGlobalSoundRecordingFamilies(filter: $filter, pagination: { limit: 100, orderBy: \"streams_28_days\", orderDir: \"DESC\" }) { items { name isrc streams28Days } totalCount } }", "variables": { "filter": "{ \"globalParticipantIds\": [111, 222, 333], \"storeIds\": [286, 1, 187] }" } } ] }, { "terms": [ "spotify search", "search spotify", "find on spotify", "spotify track", "spotify album", "spotify product", "spotify id" ], "targets": [ "spotifyTrackSearch", "spotifyAlbumSearch", "spotifyProductSearch" ], "related": [ "SpotifyTrack", "SpotifyAlbum", "SpotifyArtist", "SpotifyTrackSearchResults", "SpotifyAlbumSearchResults", "SpotifyProductSearchResults" ], "context": "Spotify search queries powered by graphql-knowledge. Search the Spotify catalog for tracks, albums, or products by name. spotifyTrackSearch returns Spotify tracks with ISRC cross-references. spotifyAlbumSearch returns Spotify albums. spotifyProductSearch resolves Spotify albums to internal Orchard products - useful for linking external Spotify content to catalog items. All return paginated results with items, total, limit, offset. SpotifyTrack includes id, name, artists, album, externalIds (ISRC). SpotifyAlbum includes id, name, albumType, images.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Search Spotify for a track by name", "query": "query ($term: String!) { spotifyTrackSearch(term: $term, limit: 10) { items { id name artists { name } externalIds { isrc } } total } }", "variables": { "term": "Shape of You" } } ] }, { "terms": [ "listener demographics", "age demographics", "gender demographics", "fan age", "fan gender", "who listens", "audience breakdown", "age group", "listener profile" ], "targets": [ "globalParticipantBySpotifyId", "globalParticipantByGpId", "globalSoundRecordingByIsrc" ], "related": [ "GlobalParticipantDemographics", "GlobalSoundrecordingDemographics", "GlobalSoundrecordingDemographicsApple", "PlaylistDemographics", "AccountDemographics", "Demographics", "DemographicAge", "DemographicAgeApple", "DemographicGender", "DemographicsByCountryV2" ], "context": "Demographics types from ows-analytics exposed via the federated gateway. Provide age and gender breakdowns for streaming listeners at the artist, recording, playlist, and account level. Demographics are accessed as sub-fields on parent entities (e.g., globalParticipant.demographics, globalSoundRecording.demographics). Age buckets differ by platform: Spotify (under_18, 18-22, 23-27, 28-34, 35-44, 45-59, 60+) and Apple Music (under_18, 18-24, 25-34, 35-44, 45-54, 55-64, 65+). DemographicsByCountryV2 provides per-country demographic breakdowns. Not all recordings/artists have demographic data - availability depends on stream volume thresholds set by DSPs.", "domain": "analytics", "priority": 2, "examples": [ { "question": "Get demographics for an artist by Spotify ID", "query": "query ($spotifyId: String!) { globalParticipantBySpotifyId(spotifyId: $spotifyId) { id name demographics { age { ageGroup percentage } gender { gender percentage } } } }", "variables": { "spotifyId": "6eUKZXaKkcviH0Ku9w2n3V" } } ] }, { "terms": [ "trending", "trending score", "trend score", "trending tracks", "days trending", "staying power", "market lift", "tadas", "tadas score", "tadas trends", "spotify lift", "apple lift", "tiktok lift", "what is trending", "whats hot", "whats trending" ], "targets": [ "globalSoundRecordingTadasTrends", "globalSoundRecordingTadasDataAvailability" ], "related": [ "GlobalSoundRecordingTadasTrendResults", "TadasTrendAnalytics", "TadasDataAvailability" ], "context": "Trending score queries (internally called TADAS). In Insights this feature is called 'Trending' - users may not know the TADAS name. globalSoundRecordingTadasTrends returns trending sound recordings with daysTrending, stayingPower (LOW/MEDIUM/HIGH - derived from tadas_30days_score: LOW <=0.12, MEDIUM <=0.24, HIGH >0.24), and platform-specific lift signals (spotifyLift, appleLift, tiktokLift) per market. Supports filtering by markets (country codes or 'GLOBAL'), globalParticipantIds (artist filter), and ordering by DAYS_TRENDING. Each trend item includes trendingFlags - an array of { name, market, lift, store } representing the specific signals driving the trend, prioritized by tier (S > ONE > TWO > THREE). Tier S signals: spotify_collection, spotify_lean_forward, tiktok_creations_global, tiktok_creations_country, spotify_search. Tier ONE: tiktok_views, apple_lean_forward, apple_search, tiktok_likes. globalSoundRecordingTadasDataAvailability returns the latest date for which trend data is available. Employee-only - not visible to external label users in the Insights UI.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Currently trending tracks in the US market", "query": "query { globalSoundRecordingTadasTrends(filter: { markets: [\"US\"] }, order: { by: DAYS_TRENDING, order: DESC }, limit: 20) { items { isrc name daysTrending stayingPower spotifyLift appleLift tiktokLift } totalCount } }", "variables": {} }, { "question": "Is a specific track trending globally in TADAS", "query": "query ($isrc: String!) { globalSoundRecordingTadasTrends(filter: { isrcs: [$isrc], markets: [\"GLOBAL\"] }) { items { isrc name daysTrending stayingPower stayingPowerScore trendingFlags { name market lift store } spotifyLift appleLift tiktokLift } totalCount } }", "variables": { "isrc": "USAT21301804" } }, { "question": "What countries and songs are trending for a specific artist", "query": "query ($gpId: Int!) { globalSoundRecordingTadasTrends(filter: { globalParticipantIds: [$gpId] }, order: { by: DAYS_TRENDING, order: DESC }, limit: 50) { items { isrc name market daysTrending stayingPower trendingFlags { name market lift } } totalCount } }", "variables": { "gpId": 12345 } }, { "question": "Are specific songs trending globally in TADAS", "query": "query ($isrcs: [String!]!) { globalSoundRecordingTadasTrends(filter: { isrcs: $isrcs, markets: [\"GLOBAL\"] }, order: { by: DAYS_TRENDING, order: DESC }) { items { isrc name daysTrending stayingPower spotifyLift appleLift tiktokLift } totalCount } }", "variables": { "isrcs": ["ISRC1", "ISRC2"] } } ] }, { "terms": [ "playlist search", "find playlist", "search playlists", "playlist lookup", "playlist metadata", "playlist details", "playlist followers", "playlist curator", "playlist storefronts", "playlist ids", "priority playlists", "editorial playlist", "algorithmic playlist", "filtr playlist", "filtr", "personalized playlist", "curated playlist", "new music friday playlist", "hot hits playlist" ], "targets": [ "playlistSearch", "playlistsMetadataListPaginated", "playlistStorefronts", "playlistIds" ], "related": [ "Playlist", "PlaylistSearchResult", "PlaylistSearchItem", "PlaylistsMetadataListResult", "PlaylistFilterOptions", "PlaylistCurator", "PlaylistType" ], "context": "Playlist discovery and metadata queries from graphql-knowledge. playlistSearch uses Snowflake Cortex Search for full-text search by playlist name or Spotify URI, with optional storeId filter (286=Spotify, 1=Apple Music). playlistsMetadataListPaginated fetches batch metadata with filters for curator market, account, owner, type (ALGORITHMIC, CHART, CURATED, EDITORIAL, HOT_HITS, NEW_MUSIC_FRIDAY, PERSONALIZED, RADIO, USER_GENERATED), and store. playlistStorefronts returns Apple Music regional variants. playlistIds returns all priority/hourly playlist IDs. Playlist type includes fields: playlistId, playlistName, playlistArtworkUrl, playlistFollowerCount, playlistTrackCount, playlistGenres, playlistType, playlistUri, playlistUrl, playlistCurator { curatorId, curatorName, curatorCountry }, source, storefront, smgPercent, frontlinePercent, localPercent, owner.", "domain": "playlist", "priority": 2, "examples": [ { "question": "Search for a playlist by name", "query": "query ($term: String!) { playlistSearch(term: $term, storeId: 286, limit: 10) { items { playlist { playlistId playlistName playlistFollowerCount playlistType playlistCurator { curatorName curatorCountry } } score } } }", "variables": { "term": "Today's Top Hits" } }, { "question": "Get metadata for a specific playlist", "query": "query ($storePlaylistId: ID!, $storeId: Int!) { playlist(storePlaylistId: $storePlaylistId, storeId: $storeId) { playlistName playlistFollowerCount playlistTrackCount playlistType playlistGenres playlistCurator { curatorName curatorCountry } } }", "variables": { "storePlaylistId": "37i9dQZF1DXcBWIGoYBM5M", "storeId": 286 } }, { "question": "Search for a named playlist on Amazon Music (note: playlists like 'Amazon Daily Pop' are playlists, not charts)", "query": "query ($term: String!) { playlistSearch(term: $term, storeId: 187, limit: 10) { items { playlist { playlistId playlistName playlistFollowerCount playlistType playlistCurator { curatorName curatorCountry } } score } } }", "variables": { "term": "Daily Pop" } }, { "question": "List editorial playlists with filters for curator market", "query": "query { playlistsMetadataListPaginated(filter: { types: [EDITORIAL], storeIds: [286], curatorMarkets: [\"US\"] }, pagination: { limit: 20, orderBy: \"playlistFollowerCount\", orderDir: \"DESC\" }) { items { playlistId playlistName playlistFollowerCount playlistTrackCount playlistCurator { curatorName curatorCountry } } totalCount } }", "variables": {} } ] }, { "terms": [ "playlist streams", "playlist analytics", "playlist impact", "playlist performance", "streams from playlist", "playlist placement streams", "playlist follower trend", "total vs playlist streams", "playlist breakdown", "placement breakdown" ], "targets": ["playlistPlacements"], "related": [ "PlaylistPlacement", "PlaylistPlacements", "PlaylistAnalytics", "PlaylistStreams", "PlaylistStreamsTimeSeries", "PlaylistFollowersTimeSeries", "PlaylistPlacementStreams", "PlaylistPlacementStreamsTimeseries", "PlaylistPlacementPositionTimeseries", "PlaylistPlacementsBreakdown", "PlaylistPlacementBreakdownByCountry", "TotalVsPlaylistStreamsByStore", "TopPlaylists", "TopPlaylistsPlacements", "GsrAnalyticsPlaylistPlacement", "ParticipantAnalyticsPlaylistPlacement", "ProductAnalyticsPlaylistPlacement" ], "context": "Playlist placement analytics powered by ows-playlist via the federated gateway. PlaylistPlacement includes: isrc, storePlaylistId, currentPosition, previousPosition, peakPosition, positionChange, daysOnPlaylist, lastAddedOnDate, removedOn, playlistName, playlistFollowerCount, playlistType, streams (bucketed: 1-day, 7-day, 28-day, all-time), completionRates. PlaylistPlacementStreamsTimeseries provides daily stream counts from a specific playlist. PlaylistPlacementPositionTimeseries tracks position changes over time. TotalVsPlaylistStreamsByStore compares total streams vs playlist-driven streams per store. PlaylistFollowersTimeSeries tracks follower count changes. GsrAnalyticsPlaylistPlacement, ParticipantAnalyticsPlaylistPlacement, and ProductAnalyticsPlaylistPlacement attach placement data to their parent entity types for contextual analytics.", "domain": "playlist", "priority": 2, "examples": [ { "question": "Get playlist placements with streams for a recording", "query": "query ($isrc: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { name playlistPlacements { items { playlistName storeId currentPosition peakPosition daysOnPlaylist playlistFollowerCount streams28Days } } } }", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "fansifter", "marketing artists", "marketing rosters", "fan data", "email campaigns", "text campaigns", "google audience", "meta audience", "tiktok audience", "marketing priority" ], "targets": ["fansifter", "marketingArtistsV2", "marketingRosters"], "related": [ "FsMarketingArtistsV2Result", "FsMarketingArtistsV2Item", "MarketingRostersResult", "MarketingRostersItem", "MarketingPriority", "MarketingTerritory", "FsGoogleAudience", "FsMetaAudience", "FsTiktokAudience", "FsEmailAnalytics", "FsTextCampaignAnalytics", "FsAutomatedEmailAnalytics" ], "context": "Fansifter and marketing queries from the federated gateway. fansifter is the entry point for fan data and marketing tools. marketingArtistsV2 lists artists associated with a label for marketing purposes, with optional type filter (by participant type) and virtual participant support. marketingRosters returns marketing rosters with local rep info, filterable by country. Marketing priorities track release-level marketing importance. Audience share integrations (FsGoogleAudience, FsMetaAudience, FsTiktokAudience) sync fan segments to ad platforms. Campaign analytics (FsEmailAnalytics, FsTextCampaignAnalytics) track marketing outreach performance.", "domain": "marketing", "priority": 1 }, { "terms": [ "label search", "vendor search", "subaccount search", "find label", "orchard label", "label type", "service tier", "company brand" ], "targets": ["orchardLabelSearch", "orchardLabels", "orchardLabel"], "related": [ "Label", "Vendor", "Subaccount", "LabelId", "ServiceTier", "CompanyBrand", "VendorType", "VendorStatus" ], "context": "Label/vendor queries from graphql-knowledge. orchardLabelSearch searches labels by name with filters for labelType (ALL, VENDOR, SUBACCOUNT), vendorStatuses, vendorTypes (CATALOG, FRONTLINE, CLIENT_SERVICES, D3, FILM, TV, TEST), companyBrandUuids, and includeDistributors. Vendor type includes vendorId, subaccountId, uuid, country, type, isDistributor, numSubaccounts, serviceTier. Subaccount includes vendor parent reference. Labels have a hierarchical structure: Vendor (parent) -> Subaccount (child). ServiceTiers categorize vendor service levels.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Search for labels matching a name", "query": "query ($term: String!) { orchardLabelSearch(term: $term, labelType: ALL, limit: 10) { ... on Vendor { vendorId uuid type serviceTier { name } } ... on Subaccount { vendorId subaccountId vendor { uuid } } } }", "variables": { "term": "Republic" } } ] }, { "terms": [ "youtube channel", "channel search", "video search", "youtube video search", "channel catalog", "video catalog", "youtube content" ], "targets": [ "channelCatalogSearchV2", "videoCatalogSearchV2", "channel", "channels" ], "related": [ "Channel", "ChannelSearchResult", "ChannelAnalytics", "ChannelAnalyticsData", "ChannelCatalogMetrics", "Video", "VideoSearchResult", "VideoAnalytics", "VideoAnalyticsData", "VideoCatalogMetrics", "VideoChannel", "VideoTrafficSources", "ChannelTrafficSources", "CountryVideos" ], "context": "YouTube channel and video queries from graphql-knowledge. channelCatalogSearchV2 searches channels by name with company brand filters. videoCatalogSearchV2 searches videos similarly. Channel type includes channelId, name, description, subscriberCount, videoCount, viewCount, thumbnailUrl, plus relationships to videos and globalParticipant. Video type includes videoId, name, isrc, videoContentType, timePublished, relationships to relatedGlobalSoundRecordingsV2 and channel. Analytics sub-types provide view counts, premium views, watch time, CPM, RPM, ad revenue, and traffic sources. ChannelCatalogMetrics and VideoCatalogMetrics provide aggregated performance snapshots.", "domain": "video", "priority": 2, "examples": [ { "question": "Search for a YouTube channel", "query": "query ($term: String!) { channelCatalogSearchV2(term: $term, limit: 10) { items { channelId name subscriberCount videoCount viewCount thumbnailUrl } totalCount } }", "variables": { "term": "Bad Bunny" } } ] }, { "terms": [ "global product", "album by upc", "product by upc", "global sound recording", "recording by isrc", "catalog entity", "catalog search", "product search", "recording search" ], "targets": [ "globalProductByUpc", "globalProductByUpcs", "globalSoundRecordingByIsrc", "globalSoundRecordingByIsrcs", "globalSoundRecordingSearchES", "globalProductSearchES" ], "related": [ "GlobalProduct", "GlobalSoundRecording", "GlobalSoundRecordingSearchResult", "GlobalProductSearchResult", "PublicSoundRecording", "PublicProduct", "PublicTrack" ], "context": "Catalog entity lookup and search queries from graphql-knowledge and elasticsearch. globalProductByUpc resolves an album by UPC to the canonical GlobalProduct (synthesized from internal Product nodes). globalSoundRecordingByIsrc resolves a song by ISRC. globalSoundRecordingSearchES and globalProductSearchES perform elasticsearch-based catalog search with ordering and filtering (catalogOnly, track types, label filters). Global* types are cross-platform canonical entities; Public* types (PublicSoundRecording, PublicProduct, PublicTrack) provide Chartmetric-sourced external metadata with spotifyId, appleMusicId, deezerId, tiktokId cross-references.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Look up a recording by ISRC", "query": "query ($isrc: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { id isrc name imageUrl releaseDate globalParticipants { id name } catalogProducts { productId productName upc } } }", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "market rank", "market size", "top markets", "territory ranking", "country ranking", "market streams" ], "targets": ["marketRanks"], "related": ["MarketRank", "MarketStreams", "TopMarkets"], "context": "Market ranking queries from the federated gateway. marketRanks returns market size rankings by store, optionally filtered by storeIds. TopMarkets provides the top streaming markets for a specific entity (track, artist, product). MarketStreams contains per-country stream counts. Use to understand geographic distribution of streaming consumption and identify key territories for marketing and distribution decisions.", "domain": "analytics", "priority": 1 }, { "terms": [ "recently visited", "visit history", "recent artists", "recent playlists", "recent recordings", "browsing history" ], "targets": ["recentlyVisitedItems", "recentlyVisitedPlaylists"], "related": [ "RecentlyVisitedItem", "GlobalParticipant", "GlobalSoundRecording", "Product", "Channel", "Video", "Playlist" ], "context": "User visit tracking from graphql-knowledge. recentlyVisitedItems returns a union of recently visited entities (GlobalParticipant, GlobalSoundRecording, Product, Channel, Video, Playlist) for the authenticated user. recentlyVisitedPlaylists returns recently viewed playlists specifically. Visit tracking is powered by Neo4j + Snowflake (PROFILE_PLAYLIST_VISITS). Corresponding mutation fields (recordGlobalParticipantVisit, recordPlaylistVisit, etc.) record new visits.", "domain": "user", "priority": 1 }, { "terms": [ "source of streams", "sos", "lean back", "lean forward", "active source", "passive source", "algorithmic source", "editorial source", "release radio", "discover weekly", "daily mix", "stream source", "where are streams coming from", "organic streams", "discovery source" ], "targets": [ "globalSoundRecordingByIsrc", "globalSoundRecordingByIsrcs", "globalParticipantBySpotifyId", "globalParticipantByGpId" ], "related": [ "SourceOfStreams", "StreamsBySourceOfStreams", "StreamSource", "StreamSourceFilter", "AggregatedSummaryBySOS", "AggregatedSummaryBySOSItem" ], "context": "Source of Streams (SOS) data classifies how listeners discover and play music. Accessed as sub-fields on entity analytics: globalSoundRecording.sourceOfStreams, globalSoundRecording.streamsBySourceOfStreams, globalParticipant.trackStreamsBySourceOfStreams. SourceOfStreams breaks down into active (user-initiated: search, artist page, collection, library), passive (algorithmic: release radar, discover weekly, radio, daily mix), collection (saved/library), and unknown. StreamsBySourceOfStreams provides per-source breakdowns. Use summary type SOS or SOS_DETAILED on analytics queries for aggregated breakdowns. StreamSourceFilter enum values: ARTIST, ARTISTPAGE, SEARCH, COLLECTION, LIBRARY, PLAYLIST, USERPLAYLIST, RELEASERADAR, DISCOVERWEEKLY, DAILYMIX, RADIO, BROWSE_FEATURES, CHART, SUGGESTED_VIDEOS, VOICE, EXTERNAL. 'Lean forward' = active/intentional streams; 'lean back' = passive/algorithmic streams.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Source of streams breakdown for a recording", "query": "query ($isrc: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { name sourceOfStreams { active { total value } passive { total value } collection { total value } } } }", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "skip rate", "skips", "completion rate", "saves", "saves to collection", "add to library", "save rate", "engagement metrics", "listener engagement", "listener retention" ], "targets": [ "globalSoundRecordingByIsrc", "globalParticipantBySpotifyId", "globalParticipantByGpId" ], "related": [ "GlobalParticipantAnalyticsTimeseriesItem", "GlobalSoundRecordingTimeseriesItem" ], "context": "Skip rate and saves are fields on analytics timeseries items. skipRate (Float) measures the percentage of streams where listeners skipped before the track finished - high skip rates indicate poor listener fit. skips (Long) is the raw skip count. saves (Long) measures add-to-collection/library actions indicating intentional listener engagement. These fields appear on GlobalParticipantAnalyticsTimeseriesItem and GlobalSoundRecordingTimeseriesItem. Access via entity.timeseries(type: ...) queries. Not all DSPs provide skip and save metrics - Spotify and Apple Music are the primary sources.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Daily skip rate and saves for a track", "query": "query ($isrc: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { name timeseries(type: TRACK_STREAMS_BY_SOS, startDate: \"2026-01-01\", endDate: \"2026-01-28\", storeIds: [286]) { items { date saves skipRate skips value } } } }", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "spotify followers", "monthly listeners", "follower count", "follower trend", "gained followers", "lost followers", "follower growth", "social stats", "social followers", "instagram followers", "tiktok followers", "facebook followers", "youtube followers", "twitter followers", "soundcloud followers", "deezer followers", "social account", "follower delta", "fan conversion", "popularity score", "spotify monthly listeners", "listener trend", "how many followers", "follower pattern", "follower comparison" ], "targets": [ "globalParticipantBySpotifyId", "globalParticipantByGpId", "globalParticipantSearchES" ], "related": [ "SocialAccountFollowers", "SocialAccountStatV2", "SocialAccountV2Followers", "AggregatedSocialAccountStatV2", "AggregatedParticipantSocialStatV2", "DeltaFollowersValue", "ParticipantSocialData" ], "context": "Social metrics and follower data for artists. SocialAccountFollowers provides total followers, growthPercentage, totalFollowersDifference, and daily timeseries items (each item has: date, followers, monthlyListeners, popularity, views, deltaFollowersValue). SocialAccountStatV2 contains per-date snapshots: followers (Long), monthlyListeners (Long), popularity (Int), views (Long), and deltaFollowersValue. Spotify monthly listeners are distinct from followers - monthly listeners reflect unique listeners in a rolling 28-day window while followers are explicit follows. Access via globalParticipant.socialAccounts or globalParticipant.socialStats on the participant entity. Platforms tracked: Spotify, Apple Music, Instagram, TikTok, Facebook, YouTube, X/Twitter, SoundCloud, Deezer, Shazam. For timeseries follower data, query socialAccounts with a date range (startDate/endDate) to get daily snapshots. For follower gain/loss analysis, use the deltaFollowersValue field or compare first and last values in the timeseries. Fan conversion percentage = followers / monthlyListeners.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Spotify followers and monthly listeners for an artist", "query": "query ($spotifyId: String!) { globalParticipantBySpotifyId(spotifyId: $spotifyId) { id name socialStats { followers monthlyListeners } } }", "variables": { "spotifyId": "6eUKZXaKkcviH0Ku9w2n3V" } }, { "question": "Spotify monthly listener and follower trend over a date range", "query": "query ($gpId: ID!, $startDate: String!, $endDate: String!) { globalParticipantByGpId(gpId: $gpId) { id name socialAccounts(platform: SPOTIFY, startDate: $startDate, endDate: $endDate) { platform followers { total items { date followers monthlyListeners popularity deltaFollowersValue } } } } }", "variables": { "gpId": "12345", "startDate": "2026-01-01", "endDate": "2026-01-31" } }, { "question": "Has an artist gained or lost Spotify followers in a period", "query": "query ($gpId: ID!, $startDate: String!, $endDate: String!) { globalParticipantByGpId(gpId: $gpId) { id name socialAccounts(platform: SPOTIFY, startDate: $startDate, endDate: $endDate) { followers { total growthPercentage totalFollowersDifference } } } }", "variables": { "gpId": "12345", "startDate": "2026-01-01", "endDate": "2026-01-31" } }, { "question": "Current follower counts across all social platforms for an artist", "query": "query ($gpId: ID!) { globalParticipantByGpId(gpId: $gpId) { id name socialAccounts { platform followers { total } } } }", "variables": { "gpId": "12345" } } ] }, { "terms": [ "tiktok analytics", "tiktok views", "tiktok creations", "tiktok likes", "tiktok shares", "tiktok comments", "tiktok favorites", "tiktok engagement", "tiktok performance", "how is performing on tiktok", "tiktok ugc", "tiktok pgc", "ugc vs pgc", "tiktok streams" ], "targets": ["topGlobalSoundRecordingsTiktok"], "related": [ "TiktokAnalytics", "TiktokAggregations", "TiktokScoreByCountry", "SocialContentType" ], "context": "TikTok analytics queries via the federated gateway. topGlobalSoundRecordingsTiktok returns ranked tracks by TikTok metrics. TikTok analytics are also available as sub-fields on globalSoundRecording and globalParticipant entities. Key metrics: views, creations (videos using a sound), likes, favorites, shares, comments, streams. Content type breakdown: UGC (user-generated content - fan videos) vs PGC (professionally-generated content - official artist videos). TikTok score by country shows trending momentum per market. For 'How is [artist] performing on TikTok', query the participant's TikTok analytics sub-field. For track-level TikTok data, query via globalSoundRecordingByIsrc with tiktok analytics sub-fields. Date range filtering via startDate/endDate or startDate/days parameters.", "domain": "analytics", "priority": 3, "examples": [ { "question": "TikTok engagement for a track over a date range", "query": "query ($isrc: String!, $startDate: String!, $days: Int!) { globalSoundRecordingByIsrc(isrc: $isrc) { tiktokAnalytics(startDate: $startDate, days: $days) { views creations likes favorites shares comments contentTypeBreakdown { contentType views creations likes } } } }", "variables": { "isrc": "USAT21301804", "startDate": "2026-04-08", "days": 6 } }, { "question": "How is an artist performing on TikTok", "query": "query ($gpId: ID!) { globalParticipantByGpId(gpId: $gpId) { id name tiktokAnalytics { views creations likes scoresByCountry { countryCode score } } } }", "variables": { "gpId": "12345" } } ] }, { "terms": [ "product type", "release format", "album format", "single format", "ep format", "full length", "album or single", "compilation", "release type", "is it an album", "singles vs albums" ], "targets": ["product", "products"], "related": ["Product", "ProductAnalytics", "GlobalSoundRecordingFamily"], "context": "Product/release type information. Products (releases) have a format field indicating type: 'Full Length' (album), 'Single', 'EP' (extended play). Use the product query to check format for a specific product, or products query with filters. When users ask 'is it an album or single', check the product's format field. Product listings for an artist include format information. To compare album vs single performance, query topGlobalSoundRecordingFamilies or products with format filter.", "domain": "catalog", "priority": 1, "examples": [ { "question": "List products for an artist showing type (album/single) with streams", "query": "query ($gpId: ID!) { globalParticipantByGpId(gpId: $gpId) { id name products { results { productId productName format releaseDate analytics { streams28Days streamsAllTime } } } } }", "variables": { "gpId": "12345" } } ] }, { "terms": [ "new music friday", "nmf", "friday releases", "new releases this week", "weekly new music", "nmf placement", "new music friday position" ], "targets": ["newMusicFridayByDate"], "related": ["NewMusicFridayDateMarket", "NewMusicFridayPlacement"], "context": "New Music Friday (NMF) tracking query. newMusicFridayByDate returns NMF playlist placement data for a given date across 50+ global markets. Each market has placements with position, whether the song is featured (cover art), and the Spotify playlist ID. NMF is a weekly editorial playlist on Spotify highlighting new releases - placement on NMF is a key promotional indicator. Key fields: market, position, averagePosition (across all markets), top10Rank, feature (boolean - whether song is the cover art).", "domain": "playlist", "priority": 1, "examples": [ { "question": "New Music Friday placements for a track on a specific date", "query": "query ($date: String!, $isrc: String!) { newMusicFridayByDate(date: $date) { placements(filter: { isrc: $isrc }) { isrc name markets { market position feature } averagePosition top10Rank } } }", "variables": { "date": "2026-01-31", "isrc": "USAT21301804" } } ] }, { "terms": [ "first week streams", "first week performance", "release week", "opening week", "launch performance", "compare periods", "period comparison", "week over week", "period over period" ], "targets": [ "globalSoundRecordingByIsrc", "globalParticipantByGpId", "globalParticipantBySpotifyId" ], "related": [ "GlobalSoundRecordingAnalytics", "ProductAnalytics", "GlobalParticipantAnalytics" ], "context": "Period comparison and first-week analysis patterns. For first-week performance, use analytics timeseries with startDate = release date and days = 7. For period comparison (e.g., first 7 days from release vs 7 days from Jan 1), make two analytics queries with different startDate values and the same days parameter, then compare the totals. Analytics summary responses include value, prevValue, and growthPercentage for automatic period-over-period comparison - the 'prev' values represent the equivalent prior period. For custom period comparisons beyond the built-in prev periods, execute separate queries and compute the delta.", "domain": "analytics", "priority": 2, "examples": [ { "question": "First 7 days streams from release date for a track (two-step: first fetch releaseDate, then use it as startDate)", "query": "query ($isrc: String!, $startDate: String!) { globalSoundRecordingByIsrc(isrc: $isrc) { releaseDate analytics { timeseries(startDate: $startDate, days: 7) { items { date streams } } } } }", "variables": { "isrc": "USAT21301804", "startDate": "2025-06-20" } }, { "question": "Compare 7-day streams between two different start dates", "query": "query ($isrc: String!, $startDate1: String!, $startDate2: String!) { period1: globalSoundRecordingByIsrc(isrc: $isrc) { analytics { summary(startDate: $startDate1, days: 7, breakdown: TOTAL) { items { value } } } } period2: globalSoundRecordingByIsrc(isrc: $isrc) { analytics { summary(startDate: $startDate2, days: 7, breakdown: TOTAL) { items { value } } } } }", "variables": { "isrc": "USAT21301804", "startDate1": "2025-06-20", "startDate2": "2026-01-01" } } ] } ] }