Returns messages in your workspace, newest first. Filter by leadId to read the
whole conversation with one lead — inbound replies and outbound sends in the
same list.
Filenames matching attachmentDownloadUrls. Present only when the message has attachments.
The full stored message document is returned, so you will see fields beyond those
listed above — e.g. attachmentUrls, correlationId. The fields listed
are the ones this endpoint guarantees or adds.
A message’s raw attachmentUrls point at private storage and return 403 to an API
key. Use attachmentDownloadUrls instead — those are signed and fetchable.
You only ever see messages in your own workspace. The API key you authenticate with
determines the workspace; there is no parameter to query another one.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Tuco AI","colors":{"primary":"#FF3515","light":"#FFF5F2","dark":"#111827"},"logo":{"light":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/light.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=c601a209f9f05fe52c2cd2e67d63adeb","dark":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/dark.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=2d4cbb7e9dea8411a50d67377ca76578"},"favicon":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/images/tuco_v1_round.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=0c579fbfd834a8ce1afe94ec9a63c4a6","api":{"openapi":"api-reference/openapi.json","mdx":{"auth":{"method":"bearer"},"server":"https://app.tuco.ai"}},"navbar":{"links":[{"href":"mailto:support@tuco.ai","label":"Support"}],"primary":{"type":"button","label":"Get Started","href":"https://app.tuco.ai"}},"footer":{"socials":{"x":"https://x.com/tucoai","linkedin":"https://linkedin.com/company/tuco-ai"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Dashboard","icon":"browser","href":"https://app.tuco.ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"tucoai","hasAudioNarration":false,"actualSubdomain":"tucoai","customDomains":["docs.tuco.ai"],"gitSource":{"type":"github","owner":"goforbg","repo":"tuco-docs","deployBranch":"master","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6aeca802b7a0003c6d81fc9b","collectionId":"61c22687-d2b6-4e42-b03f-fa713a160e77","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6aeca802b7a0003c6d81fc9b"},"entitlements":{},"buildId":"6aeca802b7a0003c6d81fc9b","clientVersion":"0.0.4071","searchFilterCounts":[{"language":"default","tag":"API Reference","count":98},{"language":"default","tag":"Documentation","count":65},{"language":"default","tag":"Lines \u0026 Leads","count":21},{"language":"default","tag":"Messages","count":14},{"language":"default","tag":"Goal Bots","count":14},{"language":"default","tag":"Webhooks","count":13},{"language":"default","tag":"iMessage Guides","count":13},{"language":"default","tag":"Agency","count":11},{"language":"default","tag":"Core Features","count":8},{"language":"default","tag":"Integrations","count":8}]},"assistantConfig":{"enableStarterQuestions":false},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/endpoint/get-messages","slug":"/api-reference/endpoint/get-messages","pageMetadata":{"title":"Get Message History","api":"GET /api/messages","description":"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.","href":"/api-reference/endpoint/get-messages"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,hr:`hr`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Expandable,Heading,Note,ParamField,ResponseField,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Note,{children:_jsxs(_components.p,{children:[`Pair this with `,_jsx(_components.a,{href:`/api-reference/endpoint/get-recordings`,children:`Get call recordings`}),` to\nassemble a complete history for a lead: texts here, calls there.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`overview`,children:`Overview`}),`\n`,_jsxs(_components.p,{children:[`Returns messages in your workspace, newest first. Filter by `,_jsx(_components.code,{children:`leadId`}),` to read the\n`,_jsx(_components.strong,{children:`whole conversation with one lead`}),` — inbound replies and outbound sends in the\nsame list.`]}),`\n`,_jsx(Heading,{level:`2`,id:`authentication`,children:`Authentication`}),`\n`,_jsx(_components.p,{children:`Pass your workspace API key as a Bearer token.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`Authorization:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` tuco_xxxxxxxxxxxxx`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`making-a-request`,children:`Making a request`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://app.tuco.ai/api/messages?leadId=6a4ed2d5dec1b2d01a6f7656\u0026limit=50\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer tuco_your_key\"`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`query-parameters`,children:`Query parameters`}),`\n`,_jsx(ParamField,{query:`leadId`,type:`string`,id:`param-lead-id`,children:_jsx(_components.p,{children:`Only messages for this lead — this is how you read a single conversation.\n24-character ObjectId hex.`})}),`\n`,_jsx(ParamField,{query:`lineId`,type:`string`,id:`param-line-id`,children:_jsx(_components.p,{children:`Only messages sent from this Tuco line. 24-character ObjectId hex.`})}),`\n`,_jsx(ParamField,{query:`upstreamCorrelationId`,type:`string`,id:`param-upstream-correlation-id`,children:_jsxs(_components.p,{children:[`Match the `,_jsx(_components.code,{children:`correlationId`}),` returned in a `,_jsx(_components.a,{href:`/api-reference/drip`,children:`drip`}),` `,_jsx(_components.code,{children:`202`}),` ack.\nUseful for confirming a queued drip became a real message.`]})}),`\n`,_jsx(ParamField,{query:`page`,type:`number`,id:`param-page`,children:_jsxs(_components.p,{children:[`Page number, 1-based. Default `,_jsx(_components.code,{children:`1`}),`.`]})}),`\n`,_jsx(ParamField,{query:`limit`,type:`number`,id:`param-limit`,children:_jsxs(_components.p,{children:[`Messages per page. Default `,_jsx(_components.code,{children:`50`}),`.`]})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`looking-a-conversation-up-by-phone-number`,children:`Looking a conversation up by phone number`}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`This endpoint has `,_jsx(_components.strong,{children:`no phone-number filter`}),`. `,_jsx(_components.code,{children:`leadId`}),` is the only way to scope to\none conversation.`]})}),`\n`,_jsx(_components.p,{children:`To start from a phone number, resolve the lead first, then pass its id:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# 1. find the lead`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://app.tuco.ai/api/leads?search=%2B13025550123\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer tuco_your_key\"`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# 2. read the conversation`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://app.tuco.ai/api/messages?leadId=THE_LEAD_ID\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer tuco_your_key\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`If you only need the lead’s `,_jsx(_components.strong,{children:`replies`}),` and not the full thread,\n`,_jsx(_components.a,{href:`/api-reference/endpoint/get-replies`,children:`Get replies`}),` accepts `,_jsx(_components.code,{children:`recipientPhone`}),`\ndirectly and skips the lookup.`]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`33`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`33`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"messages\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"6a4ed2d5dec1b2d01a6f7656\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Sounds good — Tuesday works.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"delivered\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"channelType\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"imessage\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"createdAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-09-17T15:28:41.632Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"fromLine\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"6a4ed2d5dec1b2d01a6f7600\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"firstName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Main\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"lastName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Line\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"phone\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"+13025550999\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"email\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"line@example.com\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"recipient\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"6a4ed2d5dec1b2d01a6f7601\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"firstName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Dana\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"lastName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Reed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"phone\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"+13025550123\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"email\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"dana@example.com\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"attachmentDownloadUrls\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://app.tuco.ai/api/attachments/crm-media/photo.jpg?u=...\u0026sig=...\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"attachmentNames\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"photo.jpg\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ],`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"pagination\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"page\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"limit\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`50`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"totalCount\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`128`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"totalPages\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`3`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(ResponseField,{name:`messages`,type:`array`,id:`param-messages`,children:[_jsx(_components.p,{children:`Messages, newest first.`}),_jsxs(Expandable,{title:`message fields`,children:[_jsx(ResponseField,{name:`_id`,type:`string`,id:`param-id`,children:`Message ID.`}),_jsx(ResponseField,{name:`message`,type:`string`,id:`param-message`,children:`Message body. Empty for attachment-only sends.`}),_jsxs(ResponseField,{name:`status`,type:`string`,id:`param-status`,children:[`Delivery status, e.g. `,_jsx(_components.code,{children:`queued`}),`, `,_jsx(_components.code,{children:`scheduled`}),`, `,_jsx(_components.code,{children:`sent`}),`, `,_jsx(_components.code,{children:`delivered`}),`, `,_jsx(_components.code,{children:`failed`}),`, `,_jsx(_components.code,{children:`cancelled`}),`.`]}),_jsxs(ResponseField,{name:`channelType`,type:`string`,id:`param-channel-type`,children:[`How it was sent — e.g. `,_jsx(_components.code,{children:`imessage`}),`, `,_jsx(_components.code,{children:`sms`}),`, `,_jsx(_components.code,{children:`email`}),`.`]}),_jsx(ResponseField,{name:`createdAt`,type:`string`,id:`param-created-at`,children:`When the message was created.`}),_jsxs(ResponseField,{name:`fromLine`,type:`object`,id:`param-from-line`,children:[`The Tuco line it was sent from (`,_jsx(_components.code,{children:`_id`}),`, `,_jsx(_components.code,{children:`firstName`}),`, `,_jsx(_components.code,{children:`lastName`}),`, `,_jsx(_components.code,{children:`phone`}),`, `,_jsx(_components.code,{children:`email`}),`). `,_jsx(_components.code,{children:`null`}),` if the line has since been removed.`]}),_jsxs(ResponseField,{name:`recipient`,type:`object`,id:`param-recipient`,children:[`The lead (`,_jsx(_components.code,{children:`_id`}),`, `,_jsx(_components.code,{children:`firstName`}),`, `,_jsx(_components.code,{children:`lastName`}),`, `,_jsx(_components.code,{children:`phone`}),`, `,_jsx(_components.code,{children:`email`}),`). `,_jsx(_components.code,{children:`null`}),` if the lead has since been removed.`]}),_jsxs(ResponseField,{name:`attachmentDownloadUrls`,type:`array`,id:`param-attachment-download-urls`,children:[`Signed, fetchable URLs for the message’s attachments — `,_jsx(_components.strong,{children:`present only when the message has attachments`}),`, max 5.`]}),_jsxs(ResponseField,{name:`attachmentNames`,type:`array`,id:`param-attachment-names`,children:[`Filenames matching `,_jsx(_components.code,{children:`attachmentDownloadUrls`}),`. Present only when the message has attachments.`]})]})]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[`The `,_jsx(_components.strong,{children:`full stored message document`}),` is returned, so you will see fields beyond those\nlisted above — e.g. `,_jsx(_components.code,{children:`attachmentUrls`}),`, `,_jsx(_components.code,{children:`correlationId`}),`. The fields listed\nare the ones this endpoint guarantees or adds.`]})}),`\n`,_jsx(ResponseField,{name:`pagination`,type:`object`,id:`param-pagination`,children:_jsxs(Expandable,{title:`pagination fields`,children:[_jsx(ResponseField,{name:`page`,type:`number`,id:`param-page-1`,children:`Current page.`}),_jsx(ResponseField,{name:`limit`,type:`number`,id:`param-limit-1`,children:`Page size used.`}),_jsx(ResponseField,{name:`totalCount`,type:`number`,id:`param-total-count`,children:`Total matching messages.`}),_jsx(ResponseField,{name:`totalPages`,type:`number`,id:`param-total-pages`,children:`Total pages available.`})]})}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`A message’s raw `,_jsx(_components.code,{children:`attachmentUrls`}),` point at private storage and return `,_jsx(_components.strong,{children:`403`}),` to an API\nkey. Use `,_jsx(_components.code,{children:`attachmentDownloadUrls`}),` instead — those are signed and fetchable.`]})}),`\n`,_jsx(Note,{children:_jsx(_components.p,{children:`You only ever see messages in your own workspace. The API key you authenticate with\ndetermines the workspace; there is no parameter to query another one.`})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`errors`,children:`Errors`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`HTTP`}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`401`}),_jsx(_components.td,{children:`Missing or invalid API key`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`400`}),_jsx(_components.td,{children:`No active workspace for this key`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`500`}),_jsx(_components.td,{children:`Unexpected server error`})]})]})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Get Message History","api":"GET /api/messages","description":"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.","href":"/api-reference/endpoint/get-messages"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Overview","slug":"overview","depth":2,"children":[]},{"title":"Authentication","slug":"authentication","depth":2,"children":[]},{"title":"Making a request","slug":"making-a-request","depth":2,"children":[{"title":"Query parameters","slug":"query-parameters","depth":3,"children":[]}]},{"title":"Looking a conversation up by phone number","slug":"looking-a-conversation-up-by-phone-number","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Errors","slug":"errors","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Get Message History","path":"/api/messages","servers":[{"url":"https://app.tuco.ai"}],"method":"get","request":{"security":[{"title":"Bearer Auth","parameters":{"header":{"Authorization":{"type":"http","scheme":"bearer","description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token."}},"query":{},"cookie":{}}}],"parameters":{"query":{"leadId":{"schema":[{"type":"string","description":"Only messages for this lead — this is how you read a single conversation. 24-character ObjectId hex."}]},"lineId":{"schema":[{"type":"string","description":"Only messages sent from this Tuco line. 24-character ObjectId hex."}]},"upstreamCorrelationId":{"schema":[{"type":"string","description":"Match the `correlationId` returned in a drip `202` ack. Useful for confirming a queued drip became a real message."}]},"page":{"schema":[{"type":"number","description":"Page number, 1-based. Default `1` ."}]},"limit":{"schema":[{"type":"number","description":"Messages per page. Default `50` ."}]}},"header":{},"cookie":{},"path":{}},"body":{}},"response":{"200":{"application/json":{"schemaArray":[{"type":"object","properties":{"messages":[{"type":"array","items":[{"type":"object","properties":{"_id":[{"type":"string","description":"Message ID."}],"message":[{"type":"string","description":"Message body. Empty for attachment-only sends."}],"status":[{"type":"string","description":"Delivery status, e.g. `queued` , `scheduled` , `sent` , `delivered` , `failed` , `cancelled` ."}],"channelType":[{"type":"string","description":"How it was sent — e.g. `imessage` , `sms` , `email` ."}],"createdAt":[{"type":"string","description":"When the message was created."}],"fromLine":[{"type":"object","properties":{},"description":"The Tuco line it was sent from ( `_id` , `firstName` , `lastName` , `phone` , `email` ). `null` if the line has since been removed."}],"recipient":[{"type":"object","properties":{},"description":"The lead ( `_id` , `firstName` , `lastName` , `phone` , `email` ). `null` if the lead has since been removed."}],"attachmentDownloadUrls":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"Signed, fetchable URLs for the message’s attachments — present only when the message has attachments , max 5."}],"attachmentNames":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"Filenames matching `attachmentDownloadUrls` . Present only when the message has attachments."}]}}],"description":"Messages, newest first."}],"pagination":[{"type":"object","properties":{"page":[{"type":"number","description":"Current page."}],"limit":[{"type":"number","description":"Page size used."}],"totalCount":[{"type":"number","description":"Total matching messages."}],"totalPages":[{"type":"number","description":"Total pages available."}]}}]}}],"examples":{"example":{"value":{"messages":[{"_id":"\u003cstring>","message":"\u003cstring>","status":"\u003cstring>","channelType":"\u003cstring>","createdAt":"\u003cstring>","fromLine":{},"recipient":{},"attachmentDownloadUrls":[{}],"attachmentNames":[{}]}],"pagination":{"page":123,"limit":123,"totalCount":123,"totalPages":123}}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"tucoai","siteName":"Tuco AI","title":"Get Message History - Tuco AI","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-12T19:45:11.982Z","originalFileLocation":"api-reference/endpoint/get-messages.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Tuco AI\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Get Message History - Tuco AI\">\u003cmeta data-mint-head property=\"og:description\" content=\"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Tuco AI\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.tuco.ai/api-reference/endpoint/get-messages\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://tucoai.mintlify.app/_mintlify/api/og/v2?division=Messages\u0026amp;title=Get+Message+History\u0026amp;description=Read+the+full+conversation+with+a+lead+%E2%80%94+inbound+and+outbound+messages+together%2C+newest+first%2C+paginated.\u0026amp;theme=6ee776b2be11f4145c07cfc0\u0026amp;signature=b7287e35df886290aa87ba919d771bc222251d22e3e7315ca6b09e4376fe9c10\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Get Message History - Tuco AI\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://tucoai.mintlify.app/_mintlify/api/og/v2?division=Messages\u0026amp;title=Get+Message+History\u0026amp;description=Read+the+full+conversation+with+a+lead+%E2%80%94+inbound+and+outbound+messages+together%2C+newest+first%2C+paginated.\u0026amp;theme=6ee776b2be11f4145c07cfc0\u0026amp;signature=b7287e35df886290aa87ba919d771bc222251d22e3e7315ca6b09e4376fe9c10\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Tuco AI\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FF3515\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.tuco.ai/api-reference/endpoint/get-messages\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/endpoint/get-messages.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.tuco.ai/#organization\",\"name\":\"Tuco AI\",\"url\":\"https://docs.tuco.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/light.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=c601a209f9f05fe52c2cd2e67d63adeb\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.tuco.ai#website\",\"name\":\"Tuco AI\",\"url\":\"https://docs.tuco.ai\",\"publisher\":{\"@id\":\"https://docs.tuco.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages#webpage\",\"url\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages\",\"name\":\"Get Message History\",\"description\":\"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\",\"dateModified\":\"2026-10-12T19:45:11.982Z\",\"isPartOf\":{\"@id\":\"https://docs.tuco.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Messages\",\"item\":\"https://docs.tuco.ai/api-reference/messages\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Get Message History\",\"item\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages#apireference\",\"headline\":\"Get Message History\",\"name\":\"Get Message History\",\"description\":\"Read the full conversation with a lead — inbound and outbound messages together, newest first, paginated.\",\"url\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages\",\"mainEntityOfPage\":{\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/get-messages#webpage\"},\"dateModified\":\"2026-10-12T19:45:11.982Z\",\"publisher\":{\"@id\":\"https://docs.tuco.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.tuco.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Tuco AI\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Tuco AI","nav":{"global":{"anchors":[{"anchor":"Dashboard","icon":"browser","href":"https://app.tuco.ai"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"API Reference","groups":[{"group":"Overview","pages":[{"title":"API Overview","icon":"code","href":"/api-reference/introduction"},{"title":"Tuco API Keys","icon":"key","href":"/api-reference/api-keys"},{"title":"Agency API Keys","icon":"building","href":"/api-reference/agency-api-keys"}]},{"group":"Webhooks","pages":[{"title":"Webhooks Overview","icon":"webhook","href":"/api-reference/endpoint/webhook"},{"title":"Message Webhooks","icon":"webhook","href":"/api-reference/message-webhooks"},{"title":"List Webhooks","api":"GET /api/webhooks","href":"/api-reference/endpoint/list-webhooks"},{"title":"Create Webhook","api":"POST /api/webhooks","href":"/api-reference/endpoint/create-webhook"},{"title":"Get Webhook","api":"GET /api/webhooks/{id}","href":"/api-reference/endpoint/get-webhook"},{"title":"Update Webhook","api":"PATCH /api/webhooks/{id}","href":"/api-reference/endpoint/update-webhook"},{"title":"Delete Webhook","api":"DELETE /api/webhooks/{id}","href":"/api-reference/endpoint/delete-webhook"},{"title":"Rotate Webhook Secret","api":"POST /api/webhooks/{id}/rotate-secret","href":"/api-reference/endpoint/rotate-webhook-secret"},{"title":"Send Test Webhook","api":"POST /api/webhooks/{id}/test","href":"/api-reference/endpoint/send-test-webhook"},{"title":"Webhook Health Check","api":"POST /api/webhooks/{id}/health-check","href":"/api-reference/endpoint/test-webhook"},{"title":"List Webhook Deliveries","api":"GET /api/webhooks/{id}/deliveries","href":"/api-reference/endpoint/list-webhook-deliveries"},{"title":"Get Webhook Delivery","api":"GET /api/webhooks/{id}/deliveries/{deliveryId}","href":"/api-reference/endpoint/get-webhook-delivery"},{"title":"Replay Webhook Delivery","api":"POST /api/webhooks/{id}/deliveries/{deliveryId}/replay","href":"/api-reference/endpoint/replay-webhook-delivery"}]},{"group":"Errors and status codes","pages":[{"title":"Errors \u0026 Status Codes","icon":"circle-exclamation","href":"/api-reference/errors"}]},{"group":"iMessage Availability","pages":[{"title":"Check iMessage Availability (Single Address)","api":"GET /api/check-availability","href":"/api-reference/endpoint/check-availability"},{"title":"Check iMessage Availability (Round-Robin)","api":"POST /api/check-availability-rr","href":"/api-reference/endpoint/check-availability-rr"},{"title":"Check iMessage Availability (Single Lead)","api":"GET /api/leads/check-availability","href":"/api-reference/endpoint/lead-check-availability"},{"title":"Bulk Availability Check Endpoint","api":"POST /api/leads/check-availability","href":"/api-reference/endpoint/bulk-check-availability"}]},{"group":"Messages","pages":[{"title":"Messages","icon":"paper-plane","href":"/api-reference/messages"},{"title":"Drip (bulk shock-absorber)","icon":"faucet-drip","href":"/api-reference/drip"},{"title":"Send Message","api":"POST /api/messages","description":"Send an iMessage, SMS, or email to a contact — the core automation endpoint. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON.","href":"/api-reference/endpoint/send-message"},{"title":"Get Message History","api":"GET /api/messages","href":"/api-reference/endpoint/get-messages"},{"title":"Send Drip","api":"POST /api/drip","description":"Same body as POST /api/messages, built for bulk/bursty CRM enrollment fan-out — never 429s, fast-acks 202, drips out safely per line. Bearer-token auth, JSON.","href":"/api-reference/endpoint/send-drip"},{"title":"Send Reaction","api":"POST /api/messages/react","href":"/api-reference/endpoint/send-reaction"},{"title":"Send Typing Indicator","api":"POST /api/messages/typing","href":"/api-reference/endpoint/send-typing-indicator"},{"title":"Send with Attachments","api":"POST /api/messages","href":"/api-reference/endpoint/send-with-attachments"},{"title":"Upload Attachment","openapi":"POST /api/attachments/upload","href":"/api-reference/upload-attachment"},{"title":"Cancel Pending Messages","api":"POST /api/messages/cancel-for-lead","href":"/api-reference/endpoint/cancel-for-lead"},{"title":"Read Fallback SMS Config","api":"GET /api/workspace/fallback-config","href":"/api-reference/endpoint/fallback-config"},{"title":"Update Fallback SMS Config","api":"PATCH /api/workspace/fallback-config","href":"/api-reference/endpoint/update-fallback-config"},{"title":"Atomic Duplicate Guard — POST /api/messages","href":"/imessage-double-send-guard"},{"title":"Message Status","api":"GET /api/messages/{messageId}/journey","href":"/api-reference/endpoint/message-journey"}]},{"group":"Voice / Calling","pages":[{"title":"Place a Call Endpoint","api":"POST /api/voice/calls","tag":"BETA","href":"/api-reference/endpoint/place-call"},{"title":"Get Call Recordings Endpoint","api":"GET /api/voice/recordings","tag":"BETA","href":"/api-reference/endpoint/get-recordings"},{"title":"List Recordings \u0026 Uploads Endpoint","api":"GET /api/attachments/list","tag":"BETA","href":"/api-reference/endpoint/list-recordings"}]},{"group":"Replies","pages":[{"title":"List Conversations","api":"GET /api/unibox/conversations","href":"/api-reference/endpoint/conversations"},{"title":"Check Replies","api":"GET /api/replies","href":"/api-reference/endpoint/get-replies"}]},{"group":"Do Not Contact","pages":[{"title":"List / Check Do-Not-Contact","openapi":"GET /api/dnc","href":"/api-reference/endpoint/list-dnc"},{"title":"Add to Do-Not-Contact","openapi":"POST /api/dnc","href":"/api-reference/endpoint/add-dnc"},{"title":"Bulk Add to Do-Not-Contact","openapi":"PATCH /api/dnc","href":"/api-reference/endpoint/bulk-add-dnc"}]},{"group":"Lines \u0026 Leads","pages":[{"title":"Lines API","icon":"phone","href":"/api-reference/lines"},{"title":"Get All Lines","api":"GET /api/lines/by-user","href":"/api-reference/endpoint/get-lines"},{"title":"Update a Line","api":"PATCH /api/lines/{id}","href":"/api-reference/endpoint/update-line"},{"title":"Line Plan Limits","api":"GET /api/lines/limits","href":"/api-reference/endpoint/line-limits"},{"title":"Calling Add-ons","api":"GET /api/lines/{id}/calling-addons","href":"/api-reference/endpoint/calling-addons"},{"title":"Calling Add-on Slots","api":"GET /api/lines/calling-addon-slots","href":"/api-reference/endpoint/calling-addon-slots"},{"title":"Caller ID Details","api":"GET /api/workspace/caller-id-profile","href":"/api-reference/endpoint/caller-id-profile"},{"title":"Leads API","icon":"users","href":"/api-reference/leads"},{"title":"Create / Upload Lead Endpoint","api":"POST /api/leads","href":"/api-reference/endpoint/create"},{"title":"Get \u0026 Search Leads","api":"GET /api/leads","href":"/api-reference/endpoint/get"},{"title":"Delete Lead Endpoint","api":"DELETE /api/leads","href":"/api-reference/endpoint/delete"},{"title":"List Lead Lists","api":"GET /api/lists","href":"/api-reference/endpoint/list-lists"},{"title":"Create Lead List","api":"POST /api/lists","href":"/api-reference/endpoint/create-list"},{"title":"Delete Lead List","api":"DELETE /api/lists","href":"/api-reference/endpoint/delete-list"},{"title":"List Custom Field Keys","api":"GET /api/leads/custom-field-keys","href":"/api-reference/endpoint/custom-field-keys"},{"title":"Create Line Request","api":"POST /api/line-requests","href":"/api-reference/endpoint/create-line-request"},{"title":"Get Line Request","api":"GET /api/line-requests/{id}","href":"/api-reference/endpoint/get-line-request"},{"title":"Manage Line Request","api":"POST /api/line-requests/{id}","href":"/api-reference/endpoint/manage-line-request"},{"title":"Cancel a Line","api":"POST /api/lines/cancel","href":"/api-reference/endpoint/cancel-line"},{"title":"Get Lead","api":"GET /api/leads/{id}","href":"/api-reference/endpoint/get-lead"},{"title":"Update Lead","api":"PATCH /api/leads/{id}","href":"/api-reference/endpoint/update-lead"}]},{"group":"Analytics","pages":[{"title":"Analytics","icon":"chart-line","href":"/api-reference/analytics"},{"title":"Analytics Insights","api":"GET /api/analytics/insights","href":"/api-reference/endpoint/analytics-insights"},{"title":"Analytics Day Conversations","api":"GET /api/analytics/conversations","href":"/api-reference/endpoint/analytics-conversations"}]},{"group":"Goal Bots","pages":[{"title":"List Goal Bots","api":"GET /api/goal-bots","href":"/api-reference/endpoint/list-goal-bots"},{"title":"Create Goal Bot","api":"POST /api/goal-bots","href":"/api-reference/endpoint/create-goal-bot"},{"title":"Get Goal Bot","api":"GET /api/goal-bots/{id}","href":"/api-reference/endpoint/get-goal-bot"},{"title":"Update Goal Bot","api":"PATCH /api/goal-bots/{id}","href":"/api-reference/endpoint/update-goal-bot"},{"title":"Delete Goal Bot","api":"DELETE /api/goal-bots/{id}","href":"/api-reference/endpoint/archive-goal-bot"},{"title":"Simulate Goal Bot","api":"POST /api/goal-bots/{id}/simulate","href":"/api-reference/endpoint/simulate-goal-bot"},{"title":"Reply Hours","api":"GET|PUT|DELETE /api/goal-bots/{id}/reply-hours","href":"/api-reference/endpoint/reply-hours"},{"title":"List Instruction Bots (retired)","api":"GET /api/instructions","href":"/api-reference/endpoint/list-instruction-bots"},{"title":"List Task Agents","api":"GET /api/tasks","href":"/api-reference/endpoint/list-task-agents"},{"title":"Create Task Agent","api":"POST /api/tasks","href":"/api-reference/endpoint/create-task-agent"},{"title":"Update Task Agent","api":"PATCH /api/tasks/{id}","href":"/api-reference/endpoint/update-task-agent"},{"title":"Delete Task Agent","api":"DELETE /api/tasks/{id}","href":"/api-reference/endpoint/delete-task-agent"},{"title":"Enroll Lead (instruction bots)","api":"POST /api/instructions/{id}/enroll","href":"/api-reference/endpoint/enroll-lead"},{"title":"Unenroll Lead","api":"DELETE /api/goal-bots/{id}/enroll","href":"/api-reference/endpoint/unenroll-lead"}]},{"group":"API Tools","pages":[{"title":"List API Tools","api":"GET /api/campaign-tools","href":"/api-reference/endpoint/list-tools"},{"title":"Create or Update API Tool","api":"POST /api/campaign-tools","href":"/api-reference/endpoint/save-tool"},{"title":"Delete API Tool","api":"DELETE /api/campaign-tools","href":"/api-reference/endpoint/delete-tool"},{"title":"Test API Tool","api":"POST /api/campaign-tools/test","href":"/api-reference/endpoint/test-tool"}]},{"group":"Agency","pages":[{"title":"Agency API Keys","icon":"building","href":"/api-reference/agency-api-keys"},{"title":"List Agency Workspaces","api":"GET /api/agency/subaccounts","href":"/api-reference/endpoint/agency-list-workspaces"},{"title":"Create Agency Workspace","api":"POST /api/agency/subaccounts","href":"/api-reference/endpoint/agency-create-workspace"},{"title":"Re-mint a Client Workspace Key","api":"POST /api/agency/workspace-keys","href":"/api-reference/endpoint/agency-workspace-keys"},{"title":"List Agency Lines","api":"GET /api/agency/lines","href":"/api-reference/endpoint/agency-list-lines"},{"title":"Move a Line Between Workspaces","api":"POST /api/agency/lines","href":"/api-reference/endpoint/agency-move-line"},{"title":"Agency Overview Stats","api":"GET /api/agency/overview","href":"/api-reference/endpoint/agency-overview"},{"title":"Agency Email Preferences","api":"POST /api/agency/email-preferences","href":"/api-reference/endpoint/agency-email-preferences"},{"title":"Agency Webhooks","api":"POST /api/agency/webhooks","href":"/api-reference/endpoint/agency-webhooks"},{"title":"Subscribe a Client to a Plan","api":"POST /api/agency/billing/subscribe","href":"/api-reference/endpoint/agency-subscribe"},{"title":"Monthly Statement","api":"GET /api/agency/statement","href":"/api-reference/endpoint/agency-statement"}]},{"group":"Workspace settings","pages":[{"title":"Workspace Email Preferences","api":"POST /api/email-preferences","href":"/api-reference/endpoint/email-preferences"},{"title":"Invite a Teammate","api":"POST /api/team/invite","href":"/api-reference/endpoint/team-invite"},{"title":"Force a Line Health Check","api":"GET /api/lines/check-availability","href":"/api-reference/endpoint/line-health-check"}]}]}]},"basePath":"","title":"Get Message History - Tuco AI","buildId":"dpl_GZsjphRpnhWkstV12jxWNcMHFyox","deploymentId":"dpl_GZsjphRpnhWkstV12jxWNcMHFyox","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-B5zPa4Vr.js","utils-CVjrr8Yd.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DTgURWzl.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DxTHtkdZ.js","snippetPresets-Cx47o5Vx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-4Fr6y9N_.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-Dq2ElbEk.js","shallow-BfYl9r69.js","getApiPlaygroundDisplay-Ch3xc7i1.js","CodeSnippet-BsBxuJ1v.js","CodeSnippets-CetzeDL8.js","Page-CYZot51e.js","getPastedJson-BxPKFSJx.js","icon-o0J1Ochb.js","MethodPill-Du3usO5m.js","DuplicateIcon-DJypyMzl.js","createIcon-YMA6N8KJ.js","DynamicMarkdown-CWvhfcZc.js","SectionHeading-BdLVaXCd.js","axios-vUo_bRtp.js"]}